vastly 0.2.0__tar.gz

vastly-0.2.0/.gitignore

@@ -0,0 +1,14 @@
+*.claude
+
+# User config (created on first run, never committed)
+.vastly.json
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/

vastly-0.2.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: vastly
+Version: 0.2.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/seamusfallows/vastly
+Project-URL: Issues, https://github.com/seamusfallows/vastly/issues
+Author: Seamus Fallows
+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.9
+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: Topic :: Software Development
+Requires-Python: >=3.9
+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.
+
+## Prerequisites
+
+- Python 3.9+
+- [Vast.ai CLI](https://vast.ai/docs/cli/getting-started) (`pip install vastai`) with API key configured
+- Git
+- SSH
+- [VS Code](https://code.visualstudio.com) or [Cursor](https://cursor.com) with the Remote-SSH extension
+
+## Install
+
+```sh
+pip install vastly
+```
+
+## Usage
+
+```sh
+cd your-project      # any local git repo
+vst                  # checks setup -> opens IDE (sets up on first run)
+```
+
+```sh
+vst 1xRTX4090-TW    # target a specific instance by name
+vst --no-setup       # open IDE on the remote without cloning or installing anything
+vst --version        # show version
+```
+
+## How It Works
+
+### 1. Sync
+
+Calls the Vast.ai API and writes an SSH config for each running instance to `~/.ssh/vast.d/`. On first run, adds `Include vast.d/*` to `~/.ssh/config`.
+
+Instances are named by GPU and region (e.g. `1xRTX4090-TW`, `2xA100-US`). Duplicates get the instance ID appended (`1xRTX4090-TW-12345`).
+
+### 2. Select
+
+One instance is selected automatically. Multiple instances prompt you to pick one or select all. You can also pass the name directly: `vst 1xRTX4090-TW`.
+
+### 3. Setup (first run only)
+
+For each selected instance, `vst` checks if the project has already been set up by looking for a marker file at `~/.vastly/setup/<repo>.json` on the instance. If the marker exists, it skips straight to opening the IDE.
+
+On first run (no marker), `vst` reads the remote URL from your local git repo, copies a setup script to the instance, and runs it.
+
+The setup script ([setup-remote.sh](src/vastly/data/setup-remote.sh)):
+
+- Disables auto-tmux (on by default, configurable)
+- Configures git identity from your local `git config`
+- Adds `github.com` to SSH known hosts
+- Clones your repo into the workspace
+- Installs Python dependencies (auto-detected)
+- Runs any configured post-install commands
+- Writes VS Code settings and patches `.bashrc`
+- Writes a setup marker (`~/.vastly/setup/<repo>.json`) so setup is skipped next time
+
+**Dependency auto-detection** (checked in order):
+
+1. `uv.lock` or `[tool.uv]` in pyproject.toml -- `uv sync` (installs uv if needed)
+2. `[project]` in pyproject.toml -- `pip install -e .`
+3. `requirements*.txt` -- `pip install -r` for each file
+4. `setup.py` -- `pip install -e .`
+
+Override with `installCommand` in your config.
+
+### 4. Open
+
+Launches your IDE via Remote-SSH at the project directory. If already open, focuses the existing window.
+
+## Configuration
+
+On first run, `vst` creates `~/.vastly.json` with defaults:
+
+```jsonc
+{
+  // "code" (VS Code) or "cursor"
+  "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": true,
+
+  // 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
+  // e.g. "uv sync", "pip install -e '.[dev]'", "conda env update -f environment.yml"
+  "installCommand": null
+}
+```
+
+## Troubleshooting
+
+**"Missing: vastai CLI"** -- `pip install vastai`, then `vastai set api-key <key>`.
+
+**SSH connection timeout** -- Instance may still be booting. Setup retries 3 times. Run `vastai show instances` to check status.
+
+**"Not in a git repo"** -- `vst` reads the remote URL from your local repo. Run from inside a git repo, or use `--no-setup`.

vastly-0.2.0/README.md

@@ -0,0 +1,120 @@
+# 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.
+
+## Prerequisites
+
+- Python 3.9+
+- [Vast.ai CLI](https://vast.ai/docs/cli/getting-started) (`pip install vastai`) with API key configured
+- Git
+- SSH
+- [VS Code](https://code.visualstudio.com) or [Cursor](https://cursor.com) with the Remote-SSH extension
+
+## Install
+
+```sh
+pip install vastly
+```
+
+## Usage
+
+```sh
+cd your-project      # any local git repo
+vst                  # checks setup -> opens IDE (sets up on first run)
+```
+
+```sh
+vst 1xRTX4090-TW    # target a specific instance by name
+vst --no-setup       # open IDE on the remote without cloning or installing anything
+vst --version        # show version
+```
+
+## How It Works
+
+### 1. Sync
+
+Calls the Vast.ai API and writes an SSH config for each running instance to `~/.ssh/vast.d/`. On first run, adds `Include vast.d/*` to `~/.ssh/config`.
+
+Instances are named by GPU and region (e.g. `1xRTX4090-TW`, `2xA100-US`). Duplicates get the instance ID appended (`1xRTX4090-TW-12345`).
+
+### 2. Select
+
+One instance is selected automatically. Multiple instances prompt you to pick one or select all. You can also pass the name directly: `vst 1xRTX4090-TW`.
+
+### 3. Setup (first run only)
+
+For each selected instance, `vst` checks if the project has already been set up by looking for a marker file at `~/.vastly/setup/<repo>.json` on the instance. If the marker exists, it skips straight to opening the IDE.
+
+On first run (no marker), `vst` reads the remote URL from your local git repo, copies a setup script to the instance, and runs it.
+
+The setup script ([setup-remote.sh](src/vastly/data/setup-remote.sh)):
+
+- Disables auto-tmux (on by default, configurable)
+- Configures git identity from your local `git config`
+- Adds `github.com` to SSH known hosts
+- Clones your repo into the workspace
+- Installs Python dependencies (auto-detected)
+- Runs any configured post-install commands
+- Writes VS Code settings and patches `.bashrc`
+- Writes a setup marker (`~/.vastly/setup/<repo>.json`) so setup is skipped next time
+
+**Dependency auto-detection** (checked in order):
+
+1. `uv.lock` or `[tool.uv]` in pyproject.toml -- `uv sync` (installs uv if needed)
+2. `[project]` in pyproject.toml -- `pip install -e .`
+3. `requirements*.txt` -- `pip install -r` for each file
+4. `setup.py` -- `pip install -e .`
+
+Override with `installCommand` in your config.
+
+### 4. Open
+
+Launches your IDE via Remote-SSH at the project directory. If already open, focuses the existing window.
+
+## Configuration
+
+On first run, `vst` creates `~/.vastly.json` with defaults:
+
+```jsonc
+{
+  // "code" (VS Code) or "cursor"
+  "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": true,
+
+  // 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
+  // e.g. "uv sync", "pip install -e '.[dev]'", "conda env update -f environment.yml"
+  "installCommand": null
+}
+```
+
+## Troubleshooting
+
+**"Missing: vastai CLI"** -- `pip install vastai`, then `vastai set api-key <key>`.
+
+**SSH connection timeout** -- Instance may still be booting. Setup retries 3 times. Run `vastai show instances` to check status.
+
+**"Not in a git repo"** -- `vst` reads the remote URL from your local repo. Run from inside a git repo, or use `--no-setup`.

vastly-0.2.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vastly"
+version = "0.2.0"
+description = "Connect to Vast.ai GPU instances -- sync SSH configs, set up your project, and open your IDE."
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [{ name = "Seamus Fallows" }]
+keywords = ["vast.ai", "gpu", "ssh", "remote-development"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development",
+]
+
+[project.urls]
+Repository = "https://github.com/seamusfallows/vastly"
+Issues = "https://github.com/seamusfallows/vastly/issues"
+
+[project.scripts]
+vst = "vastly.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vastly"]

vastly-0.2.0/src/vastly/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

vastly-0.2.0/src/vastly/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running vastly as ``python -m vastly``."""
+
+from vastly.cli import main
+
+if __name__ == "__main__":
+    main()

vastly-0.2.0/src/vastly/cli.py

@@ -0,0 +1,124 @@
+"""CLI entry point for the `vst` command."""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import subprocess
+
+from vastly import __version__
+from vastly.config import load_config
+from vastly.ide import check_ide, open_ide
+from vastly.instance import get_synced_instances, select_instance, show_table
+from vastly.remote import convert_to_ssh_url, setup_instances
+from vastly.ssh import run_ssh
+
+
+def _check_prerequisites(*, need_ide: bool = False, ide: str) -> bool:
+    """Verify required tools are available."""
+    ok = True
+
+    if not shutil.which("vastai"):
+        print("\033[31mMissing: vastai CLI. Install with: pip install vastai\033[0m")
+        ok = False
+    if not shutil.which("git"):
+        print("\033[31mMissing: git. Install from https://git-scm.com\033[0m")
+        ok = False
+    if not shutil.which("ssh"):
+        print("\033[31mMissing: ssh.\033[0m")
+        ok = False
+    if need_ide and not check_ide(ide):
+        urls = {"code": "https://code.visualstudio.com", "cursor": "https://cursor.com"}
+        url = urls.get(ide, "")
+        hint = f" Download from {url}" if url else ""
+        print(f"\033[31mMissing: {ide}.{hint}\033[0m")
+        ok = False
+
+    return ok
+
+
+def _local_repo_info(git_remote: str) -> tuple[str, str] | None:
+    """Return (repo_url, repo_name) from the local git repo, or None."""
+    try:
+        repo_url = subprocess.run(
+            ["git", "remote", "get-url", git_remote],
+            capture_output=True, text=True,
+        ).stdout.strip()
+    except FileNotFoundError:
+        return None
+    if not repo_url:
+        return None
+    repo_url = convert_to_ssh_url(repo_url)
+    repo_name = repo_url.rsplit("/", 1)[-1].removesuffix(".git")
+    return repo_url, repo_name
+
+
+def _connect(name: str | None, no_setup: bool) -> None:
+    """Main connect flow -- sync instances, check setup, run setup if needed, open IDE."""
+    config = load_config()
+
+    if not _check_prerequisites(need_ide=True, ide=config["ide"]):
+        return
+
+    instances = get_synced_instances(config)
+    if not instances:
+        return
+
+    show_table(instances)
+
+    selected = select_instance(instances, name)
+    if not selected:
+        return
+
+    repo_info = _local_repo_info(config["gitRemote"])
+
+    for inst in selected:
+        inst_name = inst["name"]
+
+        if no_setup or not repo_info:
+            # Skip setup -- open workspace root
+            if not repo_info and not no_setup:
+                print(f"  \033[33mNot in a git repo. Tip: run vst from inside a git repo to auto-setup.\033[0m")
+            print(f"  \033[32mOpening {config['workspace']}\033[0m")
+            open_ide(config["ide"], inst_name, config["workspace"])
+            continue
+
+        repo_url, repo_name = repo_info
+        remote_path = f"{config['workspace']}/{repo_name}"
+
+        # Check if project is already set up via marker file
+        result = run_ssh(inst_name, f"test -f ~/.vastly/setup/{repo_name}.json && echo done")
+
+        if result.returncode != 0:
+            print(f"  \033[31m{inst_name}: unreachable via SSH.\033[0m")
+            continue
+
+        if result.stdout.strip() == "done":
+            print(f"  \033[32mOpening {remote_path}\033[0m")
+            open_ide(config["ide"], inst_name, remote_path)
+            continue
+
+        # Not set up yet -- run setup
+        success = setup_instances([inst], repo_url, repo_name, config)
+        if success:
+            open_ide(config["ide"], inst_name, remote_path)
+
+
+def main() -> None:
+    """Parse arguments and run the connect flow."""
+    parser = argparse.ArgumentParser(
+        prog="vst",
+        description="Connect to a Vast.ai instance -- sync SSH, set up your project, and open your IDE.",
+        epilog=(
+            "prerequisites: vastai CLI (pip install vastai), git, ssh, VS Code or Cursor\n"
+            "config:        ~/.vastly.json (created on first run)\n"
+            "docs:          https://github.com/seamusfallows/vastly"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("name", nargs="?", help="instance name (tab-complete from ~/.ssh/vast.d/)")
+    parser.add_argument("--no-setup", action="store_true", help="open IDE without cloning or installing")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+
+    args = parser.parse_args()
+    _connect(args.name, args.no_setup)

vastly-0.2.0/src/vastly/config.py

@@ -0,0 +1,61 @@
+"""Load and manage ~/.vastly.json configuration."""
+
+from __future__ import annotations
+
+import json
+import sys
+from importlib import resources
+from pathlib import Path
+
+CONFIG_PATH = Path.home() / ".vastly.json"
+
+DEFAULTS = {
+    "ide": "code",
+    "sshUser": "root",
+    "workspace": "/workspace",
+    "disableAutoTmux": True,
+    "gitRemote": "origin",
+}
+
+
+def load_config(path: Path | None = None) -> dict:
+    """Load config from disk, creating from template if missing.
+
+    Returns a dict with all keys populated (user values override defaults).
+    """
+    path = path or CONFIG_PATH
+
+    if not path.exists():
+        template = resources.files("vastly.data").joinpath(".vastly.template.json")
+        path.write_text(template.read_text(encoding="utf-8"), encoding="utf-8")
+        print(f"Created config at {path}")
+        print("Edit it to change IDE, SSH key, port forwarding, and more.")
+
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as e:
+        print(f"\033[31mInvalid JSON in {path}: {e}\033[0m")
+        print("Fix the file or delete it to regenerate from template.")
+        sys.exit(1)
+
+    port_forwards = raw.get("portForwards")
+    if port_forwards is None:
+        port_forwards = [{"local": 8080, "remote": 8080}]
+
+    post_install = raw.get("postInstall")
+    if isinstance(post_install, str):
+        post_install = [post_install]
+    elif not post_install:
+        post_install = []
+
+    return {
+        "ide": raw.get("ide") or DEFAULTS["ide"],
+        "sshKeyPath": raw.get("sshKeyPath"),
+        "sshUser": raw.get("sshUser") or DEFAULTS["sshUser"],
+        "portForwards": list(port_forwards),
+        "workspace": raw.get("workspace") or DEFAULTS["workspace"],
+        "disableAutoTmux": raw.get("disableAutoTmux", DEFAULTS["disableAutoTmux"]),
+        "gitRemote": raw.get("gitRemote") or DEFAULTS["gitRemote"],
+        "postInstall": list(post_install),
+        "installCommand": raw.get("installCommand"),
+    }

vastly-0.2.0/src/vastly/data/.vastly.template.json

@@ -0,0 +1,13 @@
+{
+  "ide": "code",
+  "sshKeyPath": null,
+  "sshUser": "root",
+  "portForwards": [
+    { "local": 8080, "remote": 8080 }
+  ],
+  "workspace": "/workspace",
+  "disableAutoTmux": true,
+  "gitRemote": "origin",
+  "postInstall": [],
+  "installCommand": null
+}