# specter-host

Remote GPUs, locally. Run `python train.py` on cloud GPUs as if they were local.

## Install

```bash
# Recommended (isolated install)
pipx install specter-host

# Or with pip
pip install specter-host
```

## Quick Start

```bash
# Create and activate a virtual environment
python -m venv .venv && source .venv/bin/activate

# Authenticate via browser
specter login

# Provision a GPU — patches your active venv
specter install h100

# Run Python as usual — it transparently executes on the remote GPU
python train.py

# pip install works locally AND syncs to the remote automatically
pip install transformers

# When done, tear down the pod and restore your venv
specter uninstall
```

## How It Works

1. `specter install h100` provisions a cloud GPU pod via the Specter broker
2. Your active venv is patched — `bin/python` becomes a transparent proxy
   - The original binary is backed up as `python.specter-original`
   - pip, pytest, and other entry points continue to run locally
3. When you run `python train.py`, Specter:
   - Rsyncs your workspace to the remote machine
   - Executes the command via SSH
   - Streams stdout/stderr back in real-time
   - Returns the remote exit code
4. Dependencies stay in sync automatically:
   - At install time: `pip freeze` → remote `pip install`
   - After every `pip install`: auto-synced to the remote pod
5. `specter uninstall` restores your venv to its original state

## License

MIT
