Metadata-Version: 2.5
Name: vastly
Version: 0.6.0
Summary: Connect to Vast.ai GPU instances: sync SSH configs, set up your project, and open your IDE.
Project-URL: Repository, https://github.com/seamus-fallows/vastly
Project-URL: Issues, https://github.com/seamus-fallows/vastly/issues
Author: Seamus Fallows
License-File: LICENSE
Keywords: gpu,remote-development,ssh,vast.ai
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Description-Content-Type: text/markdown

# Vastly

Connect to Vast.ai GPU instances from your terminal: sync SSH configs, set up your project remotely, and open your IDE in one command.

## Install

Requires [VS Code](https://code.visualstudio.com) or [Cursor](https://cursor.com) with the Remote-SSH extension.

```sh
pip install vastly
```

This gives you two equivalent commands: `vastly` and `vst` (shorthand).

The first time you run it, `vst` asks for a Vast.ai API key ([create one here](https://cloud.vast.ai/manage-keys/)). It's saved where the [Vast.ai CLI](https://vast.ai/docs/cli/getting-started) keeps its key (`~/.config/vastai/vast_api_key`), so if you already use `vastai`, there's nothing to do -- and switching the key in one switches both. `VAST_API_KEY` overrides it. The `vastai` CLI itself isn't needed, except to log in if your account uses 2FA (see [Troubleshooting](#troubleshooting)).

## Quick Start

```sh
cd your-project      # any local git repo
vst                  # syncs SSH, sets up remote, opens IDE
```

## Why Vastly

Without vastly, you repeat this for every new instance:

```sh
# without vastly
# 1. Copy SSH command from Vast.ai dashboard
# 2. VSCode → Remote-SSH: Connect to Host → paste command
# 3. On the remote instance:
cd /workspace && git clone ...             # clone your project
pip install -r requirements.txt            # install deps
git config user.name ...                   # configure git identity
# set up git auth
# copy over .env, config files, etc. that aren't in git
# fix "Permission denied (publickey)" because you forgot -A
```

```sh
# with vastly
vst
```

`vst` does all of this for you -- syncs SSH configs with agent forwarding, clones your repo, installs deps, activates your Python environment, copies configured files not in git, and opens your IDE. On repeat runs, setup is skipped.

- **Named instances** -- `1xrtx4090-tw` instead of IPs (duplicates get the instance ID appended); pick from a list when you have multiple; assign custom aliases with `vst name`
- **Shared team accounts** -- set `owner` and vastly only touches instances labelled as yours (see [Shared Vast.ai accounts](#shared-vastai-accounts))
- **Auto-start** -- if no running instances, `vst` starts a stopped one and connects
- **Environment auto-detection** -- activates conda/venv on Vast.ai images, auto-detects uv, pip, or setup.py for dependency install
- **Git access** -- SSH agent forwarding by default, or a per-repo GitHub deploy key so the instance can only reach that one repo (see [Git access on your instance](#git-access-on-your-instance))
- **File transfer** -- `vst cp up .env` / `vst cp down results/` without remembering IPs
- **Per-project config** -- `.vastly.json` in your repo root for project-specific settings

## Commands

```sh
vst                          # connect to your instance and open IDE
vst [name]                   # connect by name or alias
vst --all                    # connect to all running instances
vst -f                       # re-run remote setup even if already done
vst -n                       # open IDE without cloning or installing
vst --git-auth MODE          # agent, auto, or deploy-key for this run
vst list                     # list all instances (running, stopped, etc.)
vst start [name | --all]     # start a stopped instance, wait, then connect
vst start -n                 # start without connecting
vst stop [name | --all] [-y]  # stop an instance (or all)
vst destroy [name | --all] [-y]  # destroy an instance (irreversible)
vst ssh [name] [command...]  # SSH into an instance or run a remote command
vst cp up|down <paths...>    # copy files to/from remote
vst name <alias> [-i inst] [--clear]  # assign a custom name to an instance
vst claim [alias] [-i inst]  # label an unlabelled instance as yours (needs "owner")
vst config                   # show current configuration
vst config --api-key         # enter a new Vast.ai API key
```

Use `-v` / `--verbose` with any command for debug output.

When you have multiple instances, commands that target a single instance prompt you to pick one. You can skip the prompt by passing a name or alias directly.

## Configuration

On first run, `vastly` creates `~/.vastly/config.json` with defaults:

```jsonc
{
  // "code" or "cursor" (auto-detected on first run; overridden when run inside an IDE terminal)
  "ide": "code",

  // Path to SSH private key. null = use your SSH config or ssh-agent
  "sshKeyPath": null,

  // SSH user on remote instances
  "sshUser": "root",

  // Ports to forward to localhost. Set to [] to disable
  // Local ports auto-increment when multiple instances are running
  "portForwards": [
    { "local": 8080, "remote": 8080 }
  ],

  // Remote directory where projects are cloned
  "workspace": "/workspace",

  // Creates ~/.no_auto_tmux to prevent auto-tmux on Vast images
  "disableAutoTmux": false,

  // Which git remote to read the repo URL from
  "gitRemote": "origin",

  // Commands to run after dependency install
  // e.g. ["curl -fsSL https://claude.ai/install.sh | bash"]
  "postInstall": [],

  // Override auto-detected install method
  // null = auto-detect (uv.lock/pyproject[tool.uv] -> pyproject[project] -> requirements*.txt -> setup.py)
  // e.g. "uv sync", "pip install -e '.[dev]'", "conda env update -f environment.yml"
  "installCommand": null,

  // Files/directories to copy from local repo to remote after setup
  // Paths are relative to the repo root. Directories are copied recursively
  // e.g. [".claude/", ".env.template"]
  "copyFiles": [],

  // How instances get git access: "agent", "auto", or "deploy-key"
  // See "Git access on your instance" below
  "gitAuth": "agent",

  // Your name in Vast.ai labels (letters and digits, e.g. "ALICE"): only
  // instances labelled ALICE or ALICE-<name> are yours. null = every instance
  // on the account is yours. See "Shared Vast.ai accounts" below
  "owner": null
}
```

### Per-project config

You can create a `.vastly.json` in your repo root to set project-specific configuration. Project config overrides the global config for these keys only:

- `postInstall`
- `installCommand`
- `workspace`
- `portForwards`
- `copyFiles`
- `gitRemote`

User-specific keys (`ide`, `sshKeyPath`, `sshUser`, `disableAutoTmux`, `gitAuth`, `owner`) are always read from the global `~/.vastly/config.json` and ignored in project configs. (A repo can't choose how your credentials are used, or which instances are yours.)

> **Note:** `postInstall` and `installCommand` run as shell commands on your remote instance during setup. When they come from a repo's `.vastly.json`, `vst` shows them and asks before running them the first time, and again whenever they change. Your own global config is never asked about.

```jsonc
// .vastly.json (in repo root)
{
  "postInstall": ["make setup"],
  "copyFiles": [".claude/"]
}
```

## Shared Vast.ai accounts

When your team shares one Vast.ai account, everyone sees everyone's instances -- and without an owner, `vst stop --all` or `vst destroy --all` would act on all of them. Set your name in `~/.vastly/config.json`:

```json
"owner": "ALICE"
```

Then an instance is yours when its Vast.ai label is `ALICE` or starts with `ALICE-` (any case), and vastly only lists, connects to, starts, stops, and destroys those. Teammates' instances get no SSH config, and right before a start, stop, or destroy vastly reads the label again, so it never acts on an instance that has become someone else's.

**Making an instance yours.** Instances you create on the Vast.ai website have no label. Run `vst claim` to label one as yours (`vst claim train` labels it `ALICE-train` and names it `train`); `vst` offers this too when none are yours yet. Only an instance with no label can be claimed, and when there's just one candidate vastly asks first -- it might be a teammate's -- showing how long ago it was created. You can also type the label on the Vast.ai website yourself.

**Names live in the label.** With an owner set, `vst name train` sets the label to `ALICE-train`, so the name follows the instance to your other computers, and teammates can see whose it is on the website.

Good to know:

- `vst list` shows your instances, the unclaimed ones, and how many others it isn't showing.
- crab-student's machines (labels ending in `-<6 hex>-<4 hex>`) are never shown, owner or not: crab-student manages them itself.
- Deploy keys of destroyed instances are cleaned up against the whole account, so a teammate's instance never loses its key.

## SSH and host keys

vastly writes one SSH config file per running instance to `~/.ssh/vast.d/`, so `ssh <name>` and your IDE work directly. Each instance's host key is trusted the first time you connect and checked every time after that, so a different machine can't pose as your instance (which matters when your SSH agent is forwarded). Keys are stored in `~/.vastly/known_hosts` under the instance's ID, so a new address after a restart, or an IP Vast.ai reuses, doesn't cause warnings. `vst destroy` removes the key.

Instances without their own SSH port are reached through Vast.ai's SSH proxy.

On Windows, vastly runs Windows' built-in OpenSSH -- the one VS Code uses -- even from Git Bash, so load your key into the Windows ssh-agent service (`ssh-add` in PowerShell), not Git Bash's agent.

## Git access on your instance

To clone and push from an instance, vastly forwards your SSH agent by default. This is common practice, and your key is never copied to the instance -- but while you're connected, whoever controls the machine could use it to reach anything your key can access.

**Recommended:** let vastly create a separate key for each repo instead. The key only works for that one repo, and vastly deletes it when you destroy the instance.

**One-time setup:**

```sh
# install the GitHub CLI: https://cli.github.com (e.g. winget install GitHub.cli, brew install gh)
gh auth login
```

Then add to `~/.vastly/config.json`:

```json
"gitAuth": "auto"
```

**What `auto` does:** uses a per-repo deploy key when you're an admin of the repo. Otherwise (for example a company repo where you're not an admin, or a repo not on GitHub) it falls back to agent forwarding and tells you why. Run `vst config` inside a repo to see which will be used.

| Setting | Behavior |
|---|---|
| `"agent"` (default) | Always forward your SSH agent |
| `"auto"` | Per-repo deploy key when possible, otherwise agent forwarding |
| `"deploy-key"` | Per-repo deploy key only; setup stops with an explanation if that's not possible |

One-off override: `vst --git-auth agent` (or `auto`, `deploy-key`).

Good to know:

- Deploy keys have write access, so you can push from the instance as usual. Agent forwarding is turned off for instances that only use deploy keys.
- Instances you set up before switching keep agent forwarding. Run `vst -f` to move them to a deploy key.
- `vst destroy` removes an instance's deploy keys. Keys left by instances destroyed elsewhere (on the Vast.ai website, or from another computer) are removed the next time vastly sets up that repo. You can always review them under your repo's **Settings > Deploy keys**: vastly's keys are titled `vastly-<account id>-<instance id>`, and it only ever removes keys for the Vast.ai account you're currently using.

**Agent forwarding tips:**

- **SSH remotes** (`git@github.com:...`): make sure your key is loaded in your SSH agent (`ssh-add -l` to check).
- **HTTPS remotes** (`https://github.com/...`): public repos clone without authentication, but pushing requires credentials. Switch to an SSH remote (`git remote set-url origin git@github.com:user/repo.git`) or use a deploy key, which always clones over SSH.

## Troubleshooting

**"This Vast.ai account needs a 2FA login" / "Your 2FA session has ended"** -- Your account uses two-factor authentication, so Vast.ai only accepts a session key from the vastai CLI. Run `vastai tfa login --method-type totp -c <code from your authenticator>` (install it with `pip install vastai`); vastly uses the session key it saves (`~/.config/vastai/vast_tfa_key`) until it expires.

**SSH connection timeout** -- Instance may still be booting. Setup retries 3 times. Run `vst list` to check status.

**"Its SSH host key has changed"** -- The instance answered with a different host key than the first time you connected. That's expected if you recycled or rebuilt it on the Vast.ai website: remove the old key with the `ssh-keygen -R ...` command vastly prints, then run `vst` again. Otherwise, don't connect.

**"Couldn't verify Vast.ai's HTTPS certificate"** -- Your Python can't find CA certificates. With Python from python.org on macOS, run `Install Certificates.command` from its folder in Applications.

**"Not in a git repo"** -- `vastly` reads the remote URL from your local repo. Run from inside a git repo, or use `vst --no-setup`.

**"Cannot access repo"** -- For SSH remotes, check that your SSH agent is running and your key is loaded (`ssh-add -l`). For HTTPS remotes, you may need a personal access token or to switch to SSH. With a deploy key, run `vst -f` to recreate it, or `vst --git-auth agent` to use agent forwarding instead (see [Git access on your instance](#git-access-on-your-instance)).

**"No Vast instances found"** -- vastly uses whichever Vast.ai account your API key belongs to. Run `vst config` to see which account is active, and `vst config --api-key` to switch.
