jambu-gpu 0.3.1__tar.gz → 0.4.0__tar.gz

{jambu_gpu-0.3.1 → jambu_gpu-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: jambu-gpu
-Version: 0.3.1
+Version: 0.4.0
 Summary: Provider-agnostic CLI for provisioning and managing temporary GPU runtimes
 Project-URL: Homepage, https://github.com/jambuai/jambu-gpu
 Project-URL: Repository, https://github.com/jambuai/jambu-gpu
@@ -47,6 +47,8 @@ When you are finished, `gpu destroy`. If you walk away, the idle timeout does it
 
 From an application in any language: `gpu --json setup` returns the OpenAI-compatible `base_url`, `api_key` and `model`, and the app uses any OpenAI SDK. See [Integrating gpu into an application](docs/INTEGRATION.md), with a ready TypeScript client.
 
+From a coding agent: `gpu agent install` gives Claude Code (or `-t cursor`, `-t desktop`) a skill and local MCP tools to rent a GPU, run the experiment and shut it down. See [Letting a coding agent rent GPUs](docs/AGENTS.md).
+
 As a last line of defense, `gpu ls` shows every jambu instance in the account and `gpu sweep --install-timer` sets up a systemd user timer that guards every project on the machine by its own rules and cleans up the orphans no project tracks. See [Keeping the account clean](docs/USAGE.md#keeping-the-account-clean).
 
 The API key is read from the environment, a project `.env`, or `~/.gpu/credentials`. It never goes in the manifest.
@@ -69,6 +71,7 @@ The file is `jambu.yaml`. This tool reads only the `gpu_runtime:` key, so other
 ## Docs
 
 - [Integrating into an application (any language)](docs/INTEGRATION.md)
+- [Letting a coding agent rent GPUs (Claude Code, Cursor, Claude Desktop)](docs/AGENTS.md)
 - [Commands, workloads, and agents](docs/USAGE.md)
 - [Every config field](docs/CONFIG.md)
 - [Choosing a model](docs/CHOOSING_A_MODEL.md)

{jambu_gpu-0.3.1 → jambu_gpu-0.4.0}/README.md

@@ -24,6 +24,8 @@ When you are finished, `gpu destroy`. If you walk away, the idle timeout does it
 
 From an application in any language: `gpu --json setup` returns the OpenAI-compatible `base_url`, `api_key` and `model`, and the app uses any OpenAI SDK. See [Integrating gpu into an application](docs/INTEGRATION.md), with a ready TypeScript client.
 
+From a coding agent: `gpu agent install` gives Claude Code (or `-t cursor`, `-t desktop`) a skill and local MCP tools to rent a GPU, run the experiment and shut it down. See [Letting a coding agent rent GPUs](docs/AGENTS.md).
+
 As a last line of defense, `gpu ls` shows every jambu instance in the account and `gpu sweep --install-timer` sets up a systemd user timer that guards every project on the machine by its own rules and cleans up the orphans no project tracks. See [Keeping the account clean](docs/USAGE.md#keeping-the-account-clean).
 
 The API key is read from the environment, a project `.env`, or `~/.gpu/credentials`. It never goes in the manifest.
@@ -46,6 +48,7 @@ The file is `jambu.yaml`. This tool reads only the `gpu_runtime:` key, so other
 ## Docs
 
 - [Integrating into an application (any language)](docs/INTEGRATION.md)
+- [Letting a coding agent rent GPUs (Claude Code, Cursor, Claude Desktop)](docs/AGENTS.md)
 - [Commands, workloads, and agents](docs/USAGE.md)
 - [Every config field](docs/CONFIG.md)
 - [Choosing a model](docs/CHOOSING_A_MODEL.md)

{jambu_gpu-0.3.1 → jambu_gpu-0.4.0}/docs/ACCEPTANCE.md

@@ -57,6 +57,22 @@ Driven end to end by [`examples/typescript-client`](../examples/typescript-clien
 
 It found two more bugs, both fixed and tested: Vast reports a stopping instance as `running` for a few seconds, which made a setup right after a stop skip the restart; and a Vast rate limit (`429`) failed setup instead of being waited out.
 
+## A coding agent driving it (0.4.0)
+
+On 2026-10-25 a headless Claude Code with no prior context (`claude -p`) was given a fresh directory holding only `gpu agent install`'s skill and `.mcp.json`, plus `VAST_API_KEY` in `.env`. It was asked in one sentence to test Qwen2.5-0.5B on a rented GPU, ask it the capital of Brazil, report time and cost, and destroy the machine. It loaded the `gpu` skill by itself and called `gpu_init` (with the cap and VRAM from the request), `gpu_validate`, `gpu_offers`, then `gpu_setup` until ready, `curl` for the question, `gpu_status`, `gpu_destroy` and `gpu_ls`. The model answered "Brasília", the account was empty at the end, and the agent reported setup time and cost correctly, noting that `session_cost_usd` leaves out the replaced host.
+
+| What was checked | What happened |
+| --- | --- |
+| Setup longer than any tool timeout | `gpu_setup` returned `running` every 300 s for 42 minutes and re-attached to the same background job each time: one machine at a time, never a second setup. |
+| Bad hosts | The first host could not pull the image for 30 minutes; setup destroyed it and rented another, which served. |
+| Cancel | Over MCP (official Python SDK client), `gpu_destroy` during a setup interrupted it like Ctrl-C: the booting machine was destroyed and `gpu_ls` came back empty, 2.3 s after the call. |
+| Protocol | The official MCP Python SDK (2.3.0) client initializes, lists the 13 tools and calls them. |
+
+The first attempt found what the unit tests had not, each fixed and tested:
+- during a setup, `gpu status`, `gpu logs`, `gpu stop` and `gpu destroy` failed on the project lock (reported as "no instance"). Now `status` and `logs` report the last saved state with `busy: true`, the MCP `gpu_stop` / `gpu_destroy` cancel the setup first, and a held lock is its own exit code, 12;
+- the host that failed last when setup gave up was not remembered as bad, so the next setup rented it again;
+- on Vast, three hosts in a row stalled 30 minutes each pulling the 12 GB Docker Hub image, and setup gave up after 90 minutes with nothing left billing. Vast now defaults to `vastai/vllm:v0.32.0-cuda-13.0`, the same vLLM that Vast's hosts cache: in the cancel test the container was running within a minute.
+
 ## The MVP command surface
 
 `jambu.yaml` schema, CLI, provider contract, provider registry, Vast.ai adapter,

jambu_gpu-0.4.0/docs/AGENTS.md

@@ -0,0 +1,56 @@
+# Letting a coding agent rent GPUs
+
+`gpu` ships a skill and a local MCP server, so Claude Code, Cursor or Claude Desktop can rent a GPU, serve a model, run an experiment against it and shut it down, from a request like "compare Qwen 7B and Llama 8B on these 50 prompts".
+
+The watchdog on the machine is what makes this safe to hand to an agent: a machine the agent forgets, or a conversation that ends mid-experiment, stops by itself after `lifecycle.idle_timeout`.
+
+## Install
+
+```bash
+pipx install jambu-gpu            # or: uv tool install jambu-gpu
+cd your-project
+echo "VAST_API_KEY=..." >> .env   # or ~/.gpu/credentials; never in jambu.yaml
+gpu agent install                 # Claude Code
+gpu agent install -t cursor       # Cursor
+gpu agent install -t desktop      # Claude Desktop
+```
+
+| Target | Skill | MCP server |
+| --- | --- | --- |
+| `claude` (default) | `.claude/skills/gpu/SKILL.md` | `.mcp.json` (Claude Code asks once to approve it) |
+| `cursor` | the same `.claude/skills/gpu/` (Cursor reads Claude's skill directories) | `.cursor/mcp.json`, with `--project ${workspaceFolder}` |
+| `desktop` | `~/.gpu/gpu-skill.zip`, to upload under Settings > Capabilities > Skills | `claude_desktop_config.json`, pinned to this project |
+
+`--global` installs for every project of the user instead: the skill in `~/.claude/skills/gpu/`, the MCP server through `claude mcp add --scope user` and in `~/.cursor/mcp.json`. Existing config files are merged; only the `gpu` entry is written. Re-running is safe.
+
+Claude Desktop and Cursor do not get your shell's environment. Keep `VAST_API_KEY` in the project `.env` or `~/.gpu/credentials`, not only in an `export`.
+
+Another agent that reads `SKILL.md` files: `gpu agent skill > path/to/skills/gpu/SKILL.md`. Any MCP client: run `gpu mcp --project /path/to/project` over stdio.
+
+## The MCP tools
+
+| Tool | Does | Costs money |
+| --- | --- | --- |
+| `gpu_init` | write `jambu.yaml` for a model, with an optional price cap and VRAM | no |
+| `gpu_validate` | check the config and credentials | no |
+| `gpu_offers` | cheapest matching machines and their price | no |
+| `gpu_setup` | rent / restart and wait for the model; returns `base_url`, `api_key`, `model` | yes |
+| `gpu_status` | state, cost so far, idle time, the watchdog's next move, setup progress | no |
+| `gpu_connection` | `base_url`, `api_key`, `model` without starting anything | no |
+| `gpu_run` | run a local command with `OPENAI_BASE_URL` / `OPENAI_API_KEY` / `JAMBU_MODEL_ID` set | yes, if it has to start the machine |
+| `gpu_logs` | runtime, onstart, watchdog or provider log | no |
+| `gpu_lock` / `gpu_unlock` | keep the machine up through a quiet period | while locked |
+| `gpu_stop` | stop now; disk kept, restart takes about a minute | ends billing for compute |
+| `gpu_destroy` | delete; needs `confirm=true` | ends all billing |
+| `gpu_ls` | every machine in the account, from any project | no |
+
+Each tool runs the `gpu` CLI with `--json` in the project directory, so errors carry the same `exit_code` as the [application contract](INTEGRATION.md#exit-codes), plus `meaning` and `next` for the agent. A tool takes an optional `project_dir`; by default it is the server's `--project`, `$GPU_PROJECT_DIR`, or the directory the client started it in.
+
+`gpu_setup` would outlast any client's tool timeout on a first rent (5–15 minutes). It starts setup as a background job, waits up to `wait_seconds` (45 by default), and reports `status: "running"` until the model answers. Calling it again re-attaches to the same job; it never starts a second machine. The job outlives the MCP server, so a client restarted mid-setup finds it again through `gpu_setup` or `gpu_status`, which answers during setup with `"busy": true` and the job's progress. `gpu_stop` and `gpu_destroy` cancel a setup in progress the way Ctrl-C does: the machine still booting is destroyed.
+
+## What keeps the agent in line
+
+- **The skill** tells the agent to show the price and ask before renting, wait out a slow setup instead of starting over, never touch `VAST_API_KEY`, and offer stop or destroy (and check `gpu_ls`) when done.
+- **The server's tool annotations** mark `gpu_destroy` destructive and the read-only tools read-only, so a client can let `gpu_status` run freely and ask for every `gpu_setup` and `gpu_destroy`. In Claude Code that is the `permissions` list in `.claude/settings.json`, e.g. `"allow": ["mcp__gpu__gpu_status", "mcp__gpu__gpu_offers", "mcp__gpu__gpu_ls"]`.
+- **`jambu.yaml`** holds the hard limits the agent cannot exceed without editing the file: `budget.max_hourly_cost_usd`, `budget.max_session_cost_usd`, `lifecycle.max_lifetime`.
+- **The watchdog** stops the machine after `idle_timeout` whatever the agent does, and `gpu sweep --install-timer` catches anything left behind.

{jambu_gpu-0.3.1 → jambu_gpu-0.4.0}/docs/CONFIG.md

@@ -91,7 +91,7 @@ each number comes from.
 | `region` | – | Comma-separated geolocations. |
 | `spot` | `false` | Use interruptible/bid capacity where supported. |
 | `host_attempts` | `3` | How many machines `setup` tries. A host that fails to boot (the provider reports it failed, it vanishes, or it is not running within `health.boot_timeout`) is destroyed, replaced from fresh offers (each held to the budget), and remembered in `$GPU_HOME/bad_hosts.json` so no setup rents it again for 24h. A model server that dies once its container runs fails at once, since the same config would fail on any machine, unless its log shows the host's network failed it (a dropped connection or timeout while downloading weights): that counts as a host failure too. Needs `lifecycle.cleanup_on_setup_failure`; without it the first failed host is kept for inspection. |
-| `image` | – | Override the runtime's container image. vLLM's default is `vllm/vllm-openai:v0.32.0`. Pin a tag: `validate` warns on `latest` or an untagged image, because the CUDA it needs can change under you. On Vast, `vastai/vllm:v0.32.0-cuda-13.0` (the same vLLM, packaged by Vast) is often cached on the host and boots in minutes where a 12 GB Docker Hub pull can stall. |
+| `image` | – | Override the runtime's container image. vLLM's default is `vllm/vllm-openai:v0.32.0`, except on Vast, where it is `vastai/vllm:v0.32.0-cuda-13.0`. Pin a tag: `validate` warns on `latest` or an untagged image, because the CUDA it needs can change under you. The Vast default (the same vLLM, packaged by Vast) is cached on many hosts, where the 12 GB Docker Hub image often stalled past `health.boot_timeout`. |
 
 ---
 

{jambu_gpu-0.3.1 → jambu_gpu-0.4.0}/docs/INTEGRATION.md

@@ -111,6 +111,7 @@ gpu env --format dotenv > .env.gpu
 | 9 | the provider cannot do this | change the config |
 | 10 | over `budget.max_hourly_cost_usd` | raise the budget or wait for cheaper offers |
 | 11 | the model server did not start (setup failed, or every host tried failed to boot) | read stderr: it carries the server's log tail; the machine was destroyed |
+| 12 | another `gpu` command holds this project's lock (usually a `setup` still booting) | wait and retry; `status` and `logs` do not fail on it, they report the last saved state with `"busy": true` |
 
 ### Lifecycle the app has to expect
 
@@ -226,7 +227,7 @@ Run `gpu --json setup` as a subprocess, parse the JSON, and point the language's
 | Symptom | Look at |
 | --- | --- |
 | `setup` fails with exit 11 | stderr has the model server's last log lines; `gpu logs --source runtime` |
-| `setup` slow on the first call | `gpu logs --source onstart`; on Vast, `compute.image: vastai/vllm:v0.32.0-cuda-13.0` pulls faster than Docker Hub's `vllm/vllm-openai` |
+| `setup` slow on the first call | `gpu status` (works during setup) and `gpu logs --source onstart`. On Vast the default image is `vastai/vllm`, which most hosts already cache; a project that pins `compute.image: vllm/vllm-openai:...` pulls 12 GB from Docker Hub |
 | `401` from the endpoint | the key changed (a new machine was rented): take it from a fresh `setup` |
 | the machine stopped while the app was busy | `gpu events`; check `idle_timeout` against the longest silence between requests, or `gpu lock` |
 | unsure what is still billing | `gpu ls` lists every jambu instance in the account |

{jambu_gpu-0.3.1 → jambu_gpu-0.4.0}/docs/USAGE.md

@@ -27,6 +27,9 @@ Operator reference. The project front page is the [README](../README.md). Field-
 | `gpu sweep --install-timer` | Write a systemd user timer running `sweep --apply`, and register this project |
 | `gpu endpoint` | Print the model endpoint URL |
 | `gpu env` | Print the base URL, API key and model as shell exports (`--format dotenv\|json`), without starting anything |
+| `gpu agent install` | Give Claude Code (`-t claude`), Cursor (`-t cursor`) or Claude Desktop (`-t desktop`) the gpu skill and MCP server ([AGENTS.md](AGENTS.md)) |
+| `gpu agent skill` | Print the bundled `SKILL.md` |
+| `gpu mcp` | The local MCP server on stdio, started by the agent's client |
 
 Every command accepts `--json` and `--config PATH`. To call `gpu` from an application in any language, see [INTEGRATION.md](INTEGRATION.md).
 

{jambu_gpu-0.3.1 → jambu_gpu-0.4.0}/jambu_gpu/__init__.py

@@ -1,5 +1,5 @@
 """gpu: provider-agnostic GPU runtime provisioning and lifecycle CLI."""
 
-__version__ = "0.3.1"
+__version__ = "0.4.0"
 
 __all__ = ["__version__"]

jambu_gpu-0.4.0/jambu_gpu/agent/__init__.py

@@ -0,0 +1 @@
+"""Agent integrations: the local MCP server, the bundled skill and their installer."""

jambu_gpu-0.4.0/jambu_gpu/agent/install.py

@@ -0,0 +1,173 @@
+"""`gpu agent install`: put the skill and the MCP server where agents look for them.
+
+One skill copy, in ``.claude/skills/gpu/`` (or ``~/.claude/skills/gpu/``),
+serves both Claude Code and Cursor, which also reads Claude's skill
+directories. The MCP server is registered per client:
+
+- claude:  ``.mcp.json`` in the project; with --global, ``claude mcp add -s user``
+- cursor:  ``.cursor/mcp.json`` in the project, or ``~/.cursor/mcp.json``
+- desktop: Claude Desktop's ``claude_desktop_config.json``, pinned to this
+  project, plus a zip of the skill to upload in Settings
+
+Existing config files are merged, never replaced: only the ``gpu`` server
+entry is written.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+import shutil
+import subprocess
+import sys
+import zipfile
+from pathlib import Path
+from typing import Any, Optional
+
+from ..core.errors import ConfigError
+from ..core.paths import gpu_home
+
+SERVER_NAME = "gpu"
+SKILL_NAME = "gpu"
+TARGETS = ("claude", "cursor", "desktop")
+
+
+def skill_source() -> Path:
+    return Path(__file__).parent / "skill" / "SKILL.md"
+
+
+def skill_text() -> str:
+    return skill_source().read_text()
+
+
+def gpu_command(portable: bool) -> list[str]:
+    """How a client starts `gpu`.
+
+    A project file that may be committed says plain ``gpu`` when it is on
+    PATH; anything machine-local uses an absolute path, because GUI apps
+    (Claude Desktop, Cursor) do not get the shell's PATH.
+    """
+    found = shutil.which("gpu")
+    if found and portable:
+        return ["gpu"]
+    if found:
+        return [str(Path(found).resolve())]
+    return [sys.executable, "-m", "jambu_gpu"]
+
+
+def desktop_config_path() -> Path:
+    system = platform.system()
+    if system == "Darwin":
+        return Path.home() / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json"
+    if system == "Windows":
+        return Path(os.environ.get("APPDATA", Path.home() / "AppData" / "Roaming")) / "Claude" / "claude_desktop_config.json"
+    base = os.environ.get("XDG_CONFIG_HOME")
+    return (Path(base) if base else Path.home() / ".config") / "Claude" / "claude_desktop_config.json"
+
+
+def merge_server(path: Path, entry: dict[str, Any]) -> str:
+    """Write ``mcpServers.gpu`` into a JSON config. Returns created/updated/unchanged."""
+    data: dict[str, Any] = {}
+    if path.is_file():
+        text = path.read_text().strip()
+        if text:
+            try:
+                data = json.loads(text)
+            except ValueError as exc:
+                raise ConfigError(f"{path} is not valid JSON ({exc}); fix it or add the gpu server by hand") from exc
+        if not isinstance(data, dict):
+            raise ConfigError(f"{path} does not hold a JSON object")
+    servers = data.setdefault("mcpServers", {})
+    if not isinstance(servers, dict):
+        raise ConfigError(f"{path}: mcpServers is not an object")
+    if servers.get(SERVER_NAME) == entry:
+        return "unchanged"
+    action = "updated" if SERVER_NAME in servers else "created"
+    servers[SERVER_NAME] = entry
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2) + "\n")
+    return action
+
+
+def write_skill(directory: Path) -> str:
+    target = directory / SKILL_NAME / "SKILL.md"
+    text = skill_text()
+    if target.is_file() and target.read_text() == text:
+        return "unchanged"
+    action = "updated" if target.exists() else "created"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(text)
+    return action
+
+
+def write_skill_zip(path: Path) -> str:
+    """The skill as Claude Desktop / claude.ai expect an upload: a folder in a zip."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with zipfile.ZipFile(path, "w", zipfile.ZIP_DEFLATED) as archive:
+        archive.writestr(f"{SKILL_NAME}/SKILL.md", skill_text())
+    return "created"
+
+
+def install(
+    targets: list[str],
+    project_dir: Path,
+    global_scope: bool = False,
+    run=subprocess.run,
+) -> dict[str, Any]:
+    """Install for each target. ``run`` is a seam for tests (``claude mcp add``)."""
+    unknown = [t for t in targets if t not in TARGETS]
+    if unknown:
+        raise ConfigError(f"unknown target {', '.join(unknown)} (choose from {', '.join(TARGETS)})")
+    project_dir = project_dir.resolve()
+    done: list[dict[str, Any]] = []
+    notes: list[str] = []
+
+    if "claude" in targets or "cursor" in targets:
+        skills = (Path.home() if global_scope else project_dir) / ".claude" / "skills"
+        done.append({"what": "skill (Claude Code, Cursor)", "path": str(skills / SKILL_NAME / "SKILL.md"), "action": write_skill(skills)})
+
+    if "claude" in targets:
+        if global_scope:
+            command = gpu_command(portable=False)
+            argv = ["claude", "mcp", "add", "--scope", "user", SERVER_NAME, "--", *command, "mcp"]
+            if shutil.which("claude"):
+                # `add` refuses an existing name; replace it so a reinstall picks up a new path.
+                run(["claude", "mcp", "remove", "--scope", "user", SERVER_NAME], capture_output=True, text=True)
+                proc = run(argv, capture_output=True, text=True)
+                if proc.returncode != 0:
+                    raise ConfigError(f"`{' '.join(argv)}` failed: {(proc.stderr or proc.stdout).strip()}")
+                done.append({"what": "MCP server (Claude Code, user scope)", "path": "claude mcp", "action": "created"})
+            else:
+                notes.append(f"claude CLI not found; register the server with: {' '.join(argv)}")
+        else:
+            command = gpu_command(portable=True)
+            entry = {"command": command[0], "args": [*command[1:], "mcp"]}
+            path = project_dir / ".mcp.json"
+            done.append({"what": "MCP server (Claude Code)", "path": str(path), "action": merge_server(path, entry)})
+            notes.append("Claude Code asks once to approve the project's .mcp.json servers")
+
+    if "cursor" in targets:
+        command = gpu_command(portable=not global_scope)
+        entry = {
+            "type": "stdio",
+            "command": command[0],
+            "args": [*command[1:], "mcp", "--project", "${workspaceFolder}"],
+        }
+        path = (Path.home() if global_scope else project_dir) / ".cursor" / "mcp.json"
+        done.append({"what": "MCP server (Cursor)", "path": str(path), "action": merge_server(path, entry)})
+
+    if "desktop" in targets:
+        command = gpu_command(portable=False)
+        entry = {"command": command[0], "args": [*command[1:], "mcp", "--project", str(project_dir)]}
+        path = desktop_config_path()
+        done.append({"what": "MCP server (Claude Desktop)", "path": str(path), "action": merge_server(path, entry)})
+        archive = gpu_home() / "gpu-skill.zip"
+        done.append({"what": "skill zip (Claude Desktop)", "path": str(archive), "action": write_skill_zip(archive)})
+        notes.append(f"Claude Desktop: restart it, then upload {archive} under Settings > Capabilities > Skills")
+        notes.append(
+            "Claude Desktop does not get your shell's environment: keep VAST_API_KEY in the "
+            "project .env or ~/.gpu/credentials"
+        )
+
+    return {"installed": done, "notes": notes}

jambu_gpu-0.4.0/jambu_gpu/agent/jobs.py

@@ -0,0 +1,193 @@
+"""`gpu setup` in the background, for callers that cannot block for 15 minutes.
+
+An MCP tool call times out long before a first setup finishes, so the MCP
+server starts setup as a detached job and reports on it when asked again.
+The job outlives the server: a client that disconnects mid-setup leaves a
+machine that either finishes booting (and is then stopped by its watchdog
+when nobody uses it) or is destroyed by setup's own failure cleanup.
+
+Files, under the project's ``.gpu/jobs/``:
+
+- ``setup.json``  pid, argv and start time
+- ``setup.out``   the command's stdout (one JSON document with --json)
+- ``setup.err``   its stderr (progress is suppressed; errors land here)
+- ``setup.rc``    the exit code, written last, when the command ends
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import signal
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Any, Optional, Sequence
+
+from ..core.paths import project_state_dir
+
+JOB_DIRNAME = "jobs"
+ERROR_TAIL_LINES = 40
+
+
+def _alive(pid: int) -> bool:
+    if os.name == "nt":  # signal 0 is CTRL_C_EVENT on Windows; trust the rc file
+        return True
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    return True
+
+
+def _tail(path: Path, lines: int) -> list[str]:
+    try:
+        text = path.read_text(errors="replace")
+    except OSError:
+        return []
+    return [line for line in text.splitlines() if line.strip()][-lines:]
+
+
+class Job:
+    """One named background command per project (only ``setup`` today)."""
+
+    def __init__(self, project_dir: Path, name: str = "setup") -> None:
+        self.dir = project_state_dir(Path(project_dir)) / JOB_DIRNAME
+        self.name = name
+        self.meta_path = self.dir / f"{name}.json"
+        self.out_path = self.dir / f"{name}.out"
+        self.err_path = self.dir / f"{name}.err"
+        self.rc_path = self.dir / f"{name}.rc"
+        self._proc: Optional[subprocess.Popen] = None
+
+    def meta(self) -> Optional[dict[str, Any]]:
+        try:
+            return json.loads(self.meta_path.read_text())
+        except (OSError, ValueError):
+            return None
+
+    def exit_code(self) -> Optional[int]:
+        try:
+            return int(self.rc_path.read_text().strip())
+        except (OSError, ValueError):
+            return None
+
+    def running(self) -> bool:
+        meta = self.meta()
+        if meta is None or self.exit_code() is not None:
+            return False
+        if self._proc is not None and self._proc.poll() is not None:
+            return False  # reaped here: our own child never lingers as a zombie
+        return _alive(int(meta["pid"]))
+
+    def start(self, argv: Sequence[str], cwd: Path) -> dict[str, Any]:
+        """Start ``argv`` detached. The caller checks ``running()`` first."""
+        self.dir.mkdir(parents=True, exist_ok=True)
+        for path in (self.out_path, self.err_path, self.rc_path):
+            path.unlink(missing_ok=True)
+        runner = [sys.executable, "-m", "jambu_gpu.agent.jobs", str(self.dir), self.name, "--", *argv]
+        kwargs: dict[str, Any] = {}
+        if os.name == "nt":
+            kwargs["creationflags"] = getattr(subprocess, "DETACHED_PROCESS", 0) | getattr(
+                subprocess, "CREATE_NEW_PROCESS_GROUP", 0
+            )
+        else:
+            kwargs["start_new_session"] = True
+        self._proc = subprocess.Popen(
+            runner,
+            cwd=str(cwd),
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            **kwargs,
+        )
+        meta = {"pid": self._proc.pid, "argv": list(argv), "started_at": time.time()}
+        self.meta_path.write_text(json.dumps(meta))
+        return meta
+
+    def wait(self, seconds: float, poll: float = 2.0) -> bool:
+        """Wait up to ``seconds`` for the job to end. True when it has."""
+        deadline = time.monotonic() + max(0.0, seconds)
+        while self.running():
+            if time.monotonic() >= deadline:
+                return False
+            time.sleep(min(poll, max(0.05, deadline - time.monotonic())))
+        return True
+
+    def cancel(self, timeout: float = 120.0) -> bool:
+        """Interrupt a running job like Ctrl-C and wait for it to clean up.
+
+        ``gpu setup`` destroys the machine it was booting when interrupted, so
+        a cancelled setup leaves nothing billing. True when the job has ended.
+        """
+        meta = self.meta()
+        if meta is None or not self.running():
+            return True
+        pid = int(meta["pid"])
+        try:
+            if os.name == "nt":
+                os.kill(pid, signal.CTRL_BREAK_EVENT)
+            else:
+                os.killpg(pid, signal.SIGINT)  # the runner leads the group (start_new_session)
+        except (ProcessLookupError, PermissionError, OSError):
+            return not self.running()
+        return self.wait(timeout, poll=1.0)
+
+    def report(self) -> dict[str, Any]:
+        """``status`` is none, running, succeeded, failed or lost (died without a code)."""
+        meta = self.meta()
+        if meta is None:
+            return {"status": "none"}
+        started = float(meta.get("started_at") or 0)
+        report: dict[str, Any] = {
+            "pid": meta.get("pid"),
+            "started_at": started,
+            "elapsed_s": round(time.time() - started, 1) if started else None,
+        }
+        if self.running():
+            report["status"] = "running"
+            return report
+        code = self.exit_code()
+        if code is None:
+            report["status"] = "lost"
+        else:
+            report["status"] = "succeeded" if code == 0 else "failed"
+            report["exit_code"] = code
+            report["finished_at"] = self.rc_path.stat().st_mtime
+            report["elapsed_s"] = round(report["finished_at"] - started, 1) if started else None
+        try:
+            report["result"] = json.loads(self.out_path.read_text())
+        except (OSError, ValueError):
+            pass
+        if report["status"] != "succeeded":
+            report["stderr_tail"] = _tail(self.err_path, ERROR_TAIL_LINES)
+        return report
+
+
+def _main(argv: list[str]) -> int:
+    """``python -m jambu_gpu.agent.jobs DIR NAME -- CMD...``: run CMD, record its exit code."""
+    directory, name = Path(argv[0]), argv[1]
+    command = argv[3:] if len(argv) > 2 and argv[2] == "--" else argv[2:]
+    # A cancel sends SIGINT to the whole group. The runner must outlive it to
+    # record the exit code, and must not kill the command while it cleans up.
+    # A Python handler (not SIG_IGN) resets to the default in the child on exec.
+    signal.signal(signal.SIGINT, lambda signum, frame: None)
+    with open(directory / f"{name}.out", "wb") as out, open(directory / f"{name}.err", "wb") as err:
+        try:
+            proc = subprocess.Popen(command, stdout=out, stderr=err, stdin=subprocess.DEVNULL)
+        except OSError as exc:
+            err.write(f"error: could not start {command[0]}: {exc}\n".encode())
+            code = 127
+        else:
+            code = proc.wait()
+    tmp = directory / f"{name}.rc.tmp"
+    tmp.write_text(str(code))
+    tmp.replace(directory / f"{name}.rc")
+    return code
+
+
+if __name__ == "__main__":
+    sys.exit(_main(sys.argv[1:]))