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

{jambu_gpu-0.2.0 → jambu_gpu-0.3.1}/.gitignore

@@ -5,6 +5,7 @@ venv/
 dist/
 build/
 *.egg-info/
+.gpu/
 .jambu/
 .env
 .env.*

{jambu_gpu-0.2.0 → jambu_gpu-0.3.1}/CONTRIBUTING.md

@@ -62,9 +62,9 @@ job queues, a web dashboard. See [docs/ACCEPTANCE.md](docs/ACCEPTANCE.md).
 
 ## Secrets
 
-Never commit credentials, `.env`, `.jambu/state.json`, or provider instance
+Never commit credentials, `.env`, `.gpu/state.json`, or provider instance
 ids from a real run. Keys are read from the environment, a gitignored `.env`,
-or `~/.jambu/credentials`. `.env.example` ships with empty values only.
+or `~/.gpu/credentials`. `.env.example` ships with empty values only.
 
 ## Pull requests
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: jambu-gpu
-Version: 0.2.0
+Version: 0.3.1
 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
@@ -49,7 +49,7 @@ From an application in any language: `gpu --json setup` returns the OpenAI-compa
 
 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 `~/.jambu/credentials`. It never goes in the manifest.
+The API key is read from the environment, a project `.env`, or `~/.gpu/credentials`. It never goes in the manifest.
 
 ## Declare
 

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

@@ -26,7 +26,7 @@ From an application in any language: `gpu --json setup` returns the OpenAI-compa
 
 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 `~/.jambu/credentials`. It never goes in the manifest.
+The API key is read from the environment, a project `.env`, or `~/.gpu/credentials`. It never goes in the manifest.
 
 ## Declare
 

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

@@ -4,7 +4,7 @@ Eighteen guarantees, mapped to the code and the test that holds each one.
 
 | # | Guarantee | Implementation | Test |
 | --- | --- | --- | --- |
-| 1 | Repeated `setup` does not duplicate infrastructure | `core/engine.py::Engine.setup` reconciles first, compares `config.fingerprint()`, and holds an exclusive `.jambu/runtime.lock` | `test_engine.py::test_setup_twice_does_not_create_two_instances`, `::test_setup_refuses_to_reuse_an_incompatible_instance` |
+| 1 | Repeated `setup` does not duplicate infrastructure | `core/engine.py::Engine.setup` reconciles first, compares `config.fingerprint()`, and holds an exclusive `.gpu/runtime.lock` | `test_engine.py::test_setup_twice_does_not_create_two_instances`, `::test_setup_refuses_to_reuse_an_incompatible_instance` |
 | 2 | Provider APIs do not leak into core orchestration | `providers/base.py` contract; all Vast wire format confined to `providers/vast/{client,mapper}.py` | `test_engine.py::test_the_core_never_branches_on_a_provider_name` (greps `core/`) |
 | 3 | Missing credentials fail before provisioning | `VastProvider.validate` returns before any API call; `CredentialResolver` never reads jambu.yaml | `test_vast_provider.py::test_validate_fails_before_provisioning_without_a_key` (asserts zero HTTP calls) |
 | 4 | Failed provisioning cleans up | `Engine.setup` persists state *before* the long wait, then destroys on failure when `cleanup_on_setup_failure` | `test_engine.py::test_failed_setup_cleans_up_partially_created_resources` |
@@ -19,7 +19,7 @@ Eighteen guarantees, mapped to the code and the test that holds each one.
 | 13 | A restarted instance stays guarded | `Engine._reconcile` takes running/stopped from the provider; the watchdog's `terminated` flag only counts when the provider cannot tell. `RuntimeState.session_started_at` restarts on every start, and `max_lifetime` and the session budget are measured from it | `test_engine_sessions.py::test_reconcile_trusts_the_provider_over_a_stale_terminated_flag`, `::test_a_stale_terminated_flag_does_not_disable_the_guard`, `::test_restarting_a_stopped_instance_starts_a_new_session`, `::test_guard_budget_resets_with_a_new_session`; watchdog-side session tests in `test_policy.py` / `test_watchdog.py` |
 | 14 | Traffic on the model endpoint is activity | `VllmRuntime.activity_probe` hands the watchdog vLLM's `/metrics` gauges and counters; `lifecycle.traffic_counts_as_activity` turns it off | `test_engine_sessions.py::test_the_watchdog_is_told_how_to_read_vllm_traffic`, `::test_traffic_can_be_excluded_from_activity`, `test_runtime_vllm.py::test_activity_probe_reads_vllm_metrics_on_loopback`; the watchdog's metrics-reading tests in `test_watchdog.py` |
 | 15 | A stopped instance does not bill storage forever | `lifecycle.stopped_ttl` -> `PolicyConfig.stopped_ttl_s`; `RuntimeState.stopped_since`; `Engine.guard_tick` destroys with reason `stopped_ttl`; `validate` warns when nothing would remove it | `test_engine_sessions.py::test_guard_destroys_an_instance_stopped_longer_than_stopped_ttl`, `::test_validate_warns_when_nothing_removes_a_billing_stopped_instance`; the stopped-TTL policy tests in `test_policy.py` |
-| 16 | Orphans are found account-wide, each project keeps its own rules, and nothing else is touched | `GPUProvider.list_instances` (capability `list_instances`) returns only `jambu-` labels; `gpu setup` registers the project in `~/.jambu/projects.json`; `core/sweep.py::guard_projects` runs each registered project's own `Engine.guard_tick`; only untracked instances are orphans: running past `--orphan-max-age` is stopped (never destroyed), stopped past `--stopped-ttl` (from the sweep's own first sighting in `~/.jambu/sweep.json`) is destroyed; `gpu sweep --install-timer` schedules one working-directory-independent unit and refuses a key that is only in the shell | `test_sweep.py::test_vast_lists_only_jambu_labelled_instances`, `::test_non_jambu_instances_are_never_touched`, `::test_another_projects_restarted_and_locked_instance_is_not_destroyed`, `::test_each_project_is_judged_by_its_own_max_lifetime`, `::test_a_running_orphan_past_orphan_max_age_is_stopped_never_destroyed`, `::test_a_stopped_orphan_is_destroyed_once_seen_stopped_past_stopped_ttl`, `::test_install_timer_writes_one_unit_independent_of_the_project`, `::test_install_timer_refuses_a_key_only_in_the_shell_environment` |
+| 16 | Orphans are found account-wide, each project keeps its own rules, and nothing else is touched | `GPUProvider.list_instances` (capability `list_instances`) returns only `jambu-` labels; `gpu setup` registers the project in `~/.gpu/projects.json`; `core/sweep.py::guard_projects` runs each registered project's own `Engine.guard_tick`; only untracked instances are orphans: running past `--orphan-max-age` is stopped (never destroyed), stopped past `--stopped-ttl` (from the sweep's own first sighting in `~/.gpu/sweep.json`) is destroyed; `gpu sweep --install-timer` schedules one working-directory-independent unit and refuses a key that is only in the shell | `test_sweep.py::test_vast_lists_only_jambu_labelled_instances`, `::test_non_jambu_instances_are_never_touched`, `::test_another_projects_restarted_and_locked_instance_is_not_destroyed`, `::test_each_project_is_judged_by_its_own_max_lifetime`, `::test_a_running_orphan_past_orphan_max_age_is_stopped_never_destroyed`, `::test_a_stopped_orphan_is_destroyed_once_seen_stopped_past_stopped_ttl`, `::test_install_timer_writes_one_unit_independent_of_the_project`, `::test_install_timer_refuses_a_key_only_in_the_shell_environment` |
 | 17 | The CLI guard never stops a serving endpoint it cannot see | `Engine._idle_blind`: with the watchdog enabled and installed but unreachable, `guard_tick` evaluates without `idle_timeout` and records `idle_skipped`; `max_lifetime`, budget and `stopped_ttl` still apply | `test_engine_sessions.py::test_guard_leaves_idle_to_an_unreachable_watchdog`, `::test_max_lifetime_still_applies_when_the_watchdog_is_unreachable` |
 | 18 | A fresh stop or a short API outage never costs the disk | `RuntimeState.mark_stopped` restarts `stopped_since` on evidence the instance ran since; the watchdog escalates a failing stop to destroy only after `escalate_after_s` (30m) of continuous failure and resets on renewed use | `test_engine_sessions.py::test_a_stale_stopped_since_does_not_destroy_a_fresh_stop`, `test_watchdog.py::test_an_api_blip_does_not_destroy_the_disk`, `::test_failures_reset_when_the_instance_is_back_in_use` |
 

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

@@ -86,10 +86,11 @@ each number comes from.
 | `gpu.count` | `1` | Number of GPUs on one machine. |
 | `gpu.name_filter` | – | Substring match, e.g. `A100`, `RTX 4090`. |
 | `gpu.cuda_min` | – | Minimum host CUDA version. `gpu` raises it to what the runtime image needs, read from its tag (`-cu129` means 12.9, vLLM's bare `v0.32+` and `latest` mean 13.0), so an image never lands on a driver too old to run it. |
+| `gpu.compute_cap_min` | – | Minimum GPU **compute capability** (architecture), e.g. `8.0` for Ampere. Distinct from `cuda_min`: a Pascal (GTX 10xx, 6.1) or Volta (V100, 7.0) card can sit behind a modern CUDA-13 driver — clearing `cuda_min` — yet still be too old for a runtime image whose kernels are built for newer architectures, which then crashes at engine startup. `gpu` raises this to what the runtime needs: a CUDA-13 vLLM image floors it at `8.0` (those wheels drop Volta), a CUDA-12 vLLM image at `7.0`. The cheapest Vast offers are often exactly these old cards, so without the floor the search keeps picking a GPU the image cannot run. |
 | `disk_gb` | `80` | Disk. Must fit the model weights plus the container. |
 | `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 `$JAMBU_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. |
+| `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. |
 
 ---

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

@@ -15,16 +15,17 @@ The app never has to stop the GPU. The watchdog on the machine stops it once not
 pipx install jambu-gpu            # or: uv tool install jambu-gpu / pip install jambu-gpu
 cd /srv/my-app                    # the directory the app runs gpu from
 gpu init --model Qwen/Qwen2.5-7B-Instruct
-echo "VAST_API_KEY=..." >> .env   # or export it, or ~/.jambu/credentials
+echo "VAST_API_KEY=..." >> .env   # or export it, or ~/.gpu/credentials
 gpu validate                      # fails here, not in production, on a bad config
 gpu sweep --install-timer         # optional safety net, see USAGE.md
 ```
 
 Requirements:
 
-- `jambu-gpu` 0.2.0 or later, on Python 3.10+. The app can be in any language.
-- The directory holding `jambu.yaml` must be **persistent**. `gpu` keeps what it rented in `.jambu/state.json` next to it. In a container, mount it as a volume: a container that loses `.jambu/` forgets its instance, rents a second one, and leaves the first to the watchdog and the sweep.
-- `.jambu/state.json` holds the endpoint key and the watchdog token. It is written `0600`. Add `.jambu/` and `.env` to `.gitignore` and keep them out of images.
+- `jambu-gpu` 0.3.0 or later, on Python 3.10+. The app can be in any language.
+- The directory holding `jambu.yaml` must be **persistent**. `gpu` keeps what it rented in `.gpu/state.json` next to it. In a container, mount it as a volume: a container that loses `.gpu/` forgets its instance, rents a second one, and leaves the first to the watchdog and the sweep.
+- Before 0.3.0 these directories were `.jambu/` and `~/.jambu`. The first command after an upgrade renames them, so an instance already rented is kept, not rented again.
+- `.gpu/state.json` holds the endpoint key and the watchdog token. It is written `0600`. Add `.gpu/` and `.env` to `.gitignore` and keep them out of images.
 
 Tune the lifecycle in `jambu.yaml` for the app. For a service with bursty traffic, a longer idle timeout avoids paying a restart on every burst:
 
@@ -218,7 +219,7 @@ Run `gpu --json setup` as a subprocess, parse the JSON, and point the language's
 - **The endpoint requires a key.** Unless `runtime.api_key` is set, `setup` generates one per machine (43 random URL-safe characters) and starts vLLM with it. Requests without it get `401`. `/health` and `/metrics` stay open: they reveal no data and the watchdog reads `/metrics`. Instances provisioned before this existed run without a key until they are recreated.
 - **The endpoint is plain HTTP** on a public IP and port. The key and the prompts travel unencrypted. For sensitive data, put the app and the GPU on a private network or a tunnel, or front the endpoint with a TLS proxy.
 - **The watchdog holds the provider key** on the instance so it can stop its own machine. A restricted key is the safer choice; see [LIFECYCLE.md](LIFECYCLE.md).
-- `jambu.yaml` never holds credentials. `.env` and `.jambu/` do not belong in version control.
+- `jambu.yaml` never holds credentials. `.env` and `.gpu/` do not belong in version control.
 
 ## 6. Troubleshooting
 

{jambu_gpu-0.2.0 → jambu_gpu-0.3.1}/docs/LIFECYCLE.md

@@ -105,7 +105,7 @@ gpu
     │
     ├── Lifecycle    core/policy.py     the only shutdown rule
     ├── Runtime      runtime/vllm.py    how the model runs
-    └── State        core/state.py      .jambu/state.json
+    └── State        core/state.py      .gpu/state.json
                 │
         Provider contract   providers/base.py
                 │

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

@@ -111,9 +111,9 @@ Vast.ai instances
 
 ### Every project by its own rules
 
-`gpu setup` (and `gpu run`, which can provision) registers the project's absolute config path in `~/.jambu/projects.json` (`$JAMBU_HOME` overrides `~/.jambu`). `gpu sweep` then works in two steps:
+`gpu setup` (and `gpu run`, which can provision) registers the project's absolute config path in `~/.gpu/projects.json` (`$GPU_HOME` overrides `~/.gpu`; a `~/.jambu` from before 0.3.0 is renamed to `~/.gpu` on first use, and `$JAMBU_HOME` is still read). `gpu sweep` then works in two steps:
 
-1. **Tracked instances.** For every registered project whose config still loads, it runs that project's own `gpu guard`: its own `jambu.yaml` and `.jambu/state.json`, so its own `max_lifetime`, lock, session start, `stopped_ttl` and budget. The project's events land in its own log. A registered project whose config file is gone is dropped from the registry. The project in the current directory, or the one given with `--config`, is guarded too for that run.
+1. **Tracked instances.** For every registered project whose config still loads, it runs that project's own `gpu guard`: its own `jambu.yaml` and `.gpu/state.json`, so its own `max_lifetime`, lock, session start, `stopped_ttl` and budget. The project's events land in its own log. A registered project whose config file is gone is dropped from the registry. The project in the current directory, or the one given with `--config`, is guarded too for that run.
 2. **Orphans.** An instance no project tracks has no known policy and nobody knows whether it is in use, so the rules are blunt but never destroy a running machine:
 
 | Orphan | Rule | Action |
@@ -134,7 +134,7 @@ $ gpu sweep
 ! 1 action(s) pending; re-run with --apply
 ```
 
-Providers do not report when an instance stopped, so the sweep keeps the time it first saw each orphan stopped in `~/.jambu/sweep.json`. An entry goes away when the instance runs again, disappears, or is tracked by a project. `stopped_ttl` for an orphan therefore counts from the first sweep that saw it stopped, never from a project's state. Every orphan action is recorded as a `sweep_action` event with its reason in `~/.jambu/logs/events.jsonl`. Credentials for the orphan step resolve the usual way (the environment, `.env` in the working directory, `~/.jambu/credentials`), then from the `.env` of registered projects.
+Providers do not report when an instance stopped, so the sweep keeps the time it first saw each orphan stopped in `~/.gpu/sweep.json`. An entry goes away when the instance runs again, disappears, or is tracked by a project. `stopped_ttl` for an orphan therefore counts from the first sweep that saw it stopped, never from a project's state. Every orphan action is recorded as a `sweep_action` event with its reason in `~/.gpu/logs/events.jsonl`. Credentials for the orphan step resolve the usual way (the environment, `.env` in the working directory, `~/.gpu/credentials`), then from the `.env` of registered projects.
 
 ### Run it on a timer
 
@@ -143,9 +143,9 @@ gpu sweep --install-timer            # every 5m; --every 15m to change
 systemctl --user daemon-reload && systemctl --user enable --now jambu-gpu-sweep.timer
 ```
 
-`--install-timer` writes `~/.config/systemd/user/jambu-gpu-sweep.service` and `.timer`, and registers the current project if there is one. The service is a single `ExecStart=<python> -m jambu_gpu sweep --apply` with the interpreter that installed it, run from `~`: which projects get guarded comes from the registry, not from the working directory, so installing from a second project changes nothing in the unit. The oneshot has a 10 minute start timeout, a failing sweep shows as a failed unit, and `JAMBU_HOME` is passed through when it is set. A unit written by an older version, with one `guard` line per project, is rewritten and those projects are registered.
+`--install-timer` writes `~/.config/systemd/user/jambu-gpu-sweep.service` and `.timer`, and registers the current project if there is one. The service is a single `ExecStart=<python> -m jambu_gpu sweep --apply` with the interpreter that installed it, run from `~`: which projects get guarded comes from the registry, not from the working directory, so installing from a second project changes nothing in the unit. The oneshot has a 10 minute start timeout, a failing sweep shows as a failed unit, and `GPU_HOME` is passed through when it is set. A unit written by an older version, with one `guard` line per project, is rewritten and those projects are registered.
 
-A user unit does not inherit your shell's environment. `--install-timer` therefore refuses unless the provider key is in a file: the project `.env` or `~/.jambu/credentials`. A key that is only exported in your shell is not enough. A user timer needs no root, but it stops at logout unless lingering is on (`loginctl enable-linger $USER`).
+A user unit does not inherit your shell's environment. `--install-timer` therefore refuses unless the provider key is in a file: the project `.env` or `~/.gpu/credentials`. A key that is only exported in your shell is not enough. A user timer needs no root, but it stops at logout unless lingering is on (`loginctl enable-linger $USER`).
 
 ```bash
 gpu sweep --uninstall-timer

{jambu_gpu-0.2.0 → jambu_gpu-0.3.1}/examples/typescript-client/README.md

@@ -6,7 +6,7 @@ Any Node/TypeScript application using a GPU that `gpu` rents and guards, through
 
 ## Run it
 
-From the directory that holds `jambu.yaml` and `VAST_API_KEY` (in `.env` or the environment), with `jambu-gpu` 0.2.0 or later on `PATH`:
+From the directory that holds `jambu.yaml` and `VAST_API_KEY` (in `.env` or the environment), with `jambu-gpu` 0.3.0 or later on `PATH`:
 
 ```bash
 npm --prefix examples/typescript-client install

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

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

{jambu_gpu-0.2.0 → jambu_gpu-0.3.1}/jambu_gpu/cli/_common.py

@@ -118,7 +118,7 @@ def fmt_money(value: Optional[float], suffix: str = "") -> Optional[str]:
 
 
 def register_project(context: Context) -> None:
-    """Put this project in $JAMBU_HOME/projects.json so `gpu sweep` guards it.
+    """Put this project in $GPU_HOME/projects.json so `gpu sweep` guards it.
 
     Done before provisioning: a setup that dies halfway must still leave an
     instance the sweep judges by this project's policy, not as an orphan.

{jambu_gpu-0.2.0 → jambu_gpu-0.3.1}/jambu_gpu/cli/account.py

@@ -57,7 +57,7 @@ class Account:
 
 
 def account_credentials(project_dir: Path, profile: str = "default") -> CredentialResolver:
-    """The environment, ./.env, ~/.jambu/credentials, then registered projects' .env.
+    """The environment, ./.env, ~/.gpu/credentials, then registered projects' .env.
 
     The timer runs from ~ without the shell's environment; a key kept only in
     a project's .env must still reach the account-wide orphan sweep.
@@ -196,7 +196,7 @@ def _require_file_credentials(context: Context) -> None:
             raise ConfigError(
                 f"{name} is {where}, so the timer could not use it for {who}: a systemd "
                 f"user unit does not inherit your shell. Put `{name}=...` in "
-                "~/.jambu/credentials (chmod 600), then re-run --install-timer."
+                "~/.gpu/credentials (chmod 600), then re-run --install-timer."
             )
 
 

{jambu_gpu-0.2.0 → jambu_gpu-0.3.1}/jambu_gpu/cli/main.py

@@ -19,7 +19,7 @@ app = typer.Typer(
     name="gpu",
     help=(
         "Provider-agnostic CLI for provisioning and managing temporary GPU runtimes.\n\n"
-        "jambu.yaml is the desired-state source of truth; .jambu/state.json is what "
+        "jambu.yaml is the desired-state source of truth; .gpu/state.json is what "
         "was last observed."
     ),
     no_args_is_help=True,

{jambu_gpu-0.2.0 → jambu_gpu-0.3.1}/jambu_gpu/cli/timer.py

@@ -1,9 +1,9 @@
 """systemd *user* units that run `gpu sweep --apply` on a timer.
 
 One ``ExecStart`` covers every project: the sweep guards each project in
-``$JAMBU_HOME/projects.json`` with its own config, so the unit does not depend
+``$GPU_HOME/projects.json`` with its own config, so the unit does not depend
 on its working directory. A user unit needs no root, but it does not inherit
-the shell's environment: credentials must live in ``~/.jambu/credentials`` or
+the shell's environment: credentials must live in ``~/.gpu/credentials`` or
 the project ``.env``. Writing the files is all this module does; enabling them
 is left to the printed ``systemctl`` command.
 """
@@ -64,7 +64,7 @@ def render_units(
         f"TimeoutStartSec={START_TIMEOUT}",
     ]
     if jambu_home:
-        lines.append(_environment("JAMBU_HOME", jambu_home))
+        lines.append(_environment("GPU_HOME", jambu_home))
     # No "-" prefix: a failing sweep must show up as a failed unit.
     lines.append("ExecStart=" + " ".join(_quote(a) for a in [python, "-m", "jambu_gpu", "sweep", "--apply"]))
     lines.append("")
@@ -115,7 +115,9 @@ def install_timer(every_s: float, python: Optional[str] = None) -> dict:
     service_path, timer_path = unit_paths()
     legacy = legacy_guard_configs(service_path)
     service, timer = render_units(
-        every_s=every_s, python=python, jambu_home=os.environ.get("JAMBU_HOME") or None
+        every_s=every_s,
+        python=python,
+        jambu_home=os.environ.get("GPU_HOME") or os.environ.get("JAMBU_HOME") or None,
     )
     service_path.parent.mkdir(parents=True, exist_ok=True)
     service_path.write_text(service)

{jambu_gpu-0.2.0 → jambu_gpu-0.3.1}/jambu_gpu/core/config.py

@@ -33,12 +33,12 @@ from pydantic import BaseModel, ConfigDict, Field, field_validator, model_valida
 
 from .durations import parse_duration
 from .errors import ConfigError
+from .paths import project_state_dir
 
 # jambu.yaml (namespaced, shared with other Jambu Lab tools) is searched
 # first; config.yml (flat, gpu-runtime-only) is the legacy fallback.
 CONFIG_FILENAMES = ("jambu.yaml", "jambu.yml", "config.yml", "config.yaml")
 GPU_RUNTIME_KEY = "gpu_runtime"
-STATE_DIRNAME = ".jambu"
 
 # The model catalog (spec: "Choosing a model" doc) - a project's jambu.yaml
 # references one entry by name instead of redeclaring the whole model/compute/
@@ -79,6 +79,11 @@ class GpuConfig(_Base):
     count: int = 1
     name_filter: Optional[str] = None
     cuda_min: Optional[str] = None
+    # Minimum GPU compute capability (architecture), e.g. 8.0 to require
+    # Ampere or newer. Raised to what the runtime needs; see
+    # ModelRuntime.required_compute_cap. Leave unset to accept the runtime's
+    # own floor.
+    compute_cap_min: Optional[float] = None
 
     @field_validator("count")
     @classmethod
@@ -319,7 +324,7 @@ class RuntimeConfig(_Base):
 
     @property
     def state_dir(self) -> Path:
-        return self.project_dir / STATE_DIRNAME
+        return project_state_dir(self.project_dir)
 
     def fingerprint(self) -> str:
         """Identity of the *desired* runtime.

{jambu_gpu-0.2.0 → jambu_gpu-0.3.1}/jambu_gpu/core/credentials.py

@@ -1,7 +1,7 @@
 """Credential resolution (spec section 5).
 
 Credentials never live in jambu.yaml. They are resolved from, in order:
-environment variables, a project-local ``.env``, then ``~/.jambu/credentials``.
+environment variables, a project-local ``.env``, then ``~/.gpu/credentials``.
 The resolution strategy can grow (keychain, secret managers, CI secrets)
 without touching jambu.yaml or any adapter.
 """
@@ -12,6 +12,8 @@ import os
 from pathlib import Path
 from typing import Optional
 
+from .paths import gpu_home
+
 _DOTENV_CACHE: dict[Path, dict[str, str]] = {}
 
 
@@ -46,7 +48,7 @@ class CredentialResolver:
         self.profile = profile
         self.sources: list[tuple[str, Path]] = [
             ("project .env", self.project_dir / ".env"),
-            ("user credentials", Path.home() / ".jambu" / "credentials"),
+            ("user credentials", gpu_home() / "credentials"),
             *(extra_sources or []),
         ]
 

{jambu_gpu-0.2.0 → jambu_gpu-0.3.1}/jambu_gpu/core/engine.py

@@ -366,6 +366,7 @@ class Engine:
                 count=cfg.compute.gpu.count,
                 name_filter=cfg.compute.gpu.name_filter,
                 cuda_min=self.cuda_min(),
+                compute_cap_min=self.compute_cap_min(),
             ),
             disk_gb=cfg.compute.disk_gb,
             image=self.runtime.image(),
@@ -389,6 +390,18 @@ class Engine:
             return configured
         return f"{needed:.1f}"
 
+    def compute_cap_min(self) -> Optional[float]:
+        """The stricter of compute.gpu.compute_cap_min and the runtime's floor."""
+        candidates = [
+            c
+            for c in (
+                self.config.compute.gpu.compute_cap_min,
+                self.runtime.required_compute_cap(),
+            )
+            if c is not None
+        ]
+        return max(candidates) if candidates else None
+
     def _ports(self) -> list[int]:
         ports = list(self.runtime.ports())
         if self.config.lifecycle.watchdog.enabled:

{jambu_gpu-0.2.0 → jambu_gpu-0.3.1}/jambu_gpu/core/events.py

@@ -1,6 +1,6 @@
 """Structured lifecycle events (spec section 24).
 
-Every lifecycle action appends one JSON object to ``.jambu/logs/events.jsonl``
+Every lifecycle action appends one JSON object to ``.gpu/logs/events.jsonl``
 so unexpected GPU cost can always be traced back to a decision and a reason.
 """
 

{jambu_gpu-0.2.0 → jambu_gpu-0.3.1}/jambu_gpu/core/hosts.py

@@ -2,7 +2,7 @@
 
 A host that could not pull the image or reach the network fails the next
 setup the same way, and the cheapest-offer search keeps picking it. Each
-failure is kept for ``BAD_HOST_TTL_S`` in ``$JAMBU_HOME/bad_hosts.json``.
+failure is kept for ``BAD_HOST_TTL_S`` in ``$GPU_HOME/bad_hosts.json``.
 """
 
 from __future__ import annotations

{jambu_gpu-0.2.0 → jambu_gpu-0.3.1}/jambu_gpu/core/models.py

@@ -91,6 +91,11 @@ class GpuSpec:
     count: int = 1
     name_filter: Optional[str] = None
     cuda_min: Optional[str] = None
+    # Minimum GPU compute capability (architecture), e.g. 8.0 for Ampere. The
+    # host driver's CUDA (``cuda_min``) is not the same thing: a Pascal/Volta
+    # card can sit behind a CUDA-13 driver yet still be too old for a runtime
+    # image built for newer architectures, which then dies at engine startup.
+    compute_cap_min: Optional[float] = None
 
 
 @dataclass
@@ -127,6 +132,9 @@ class Offer:
     score: Optional[float] = None
     # Highest CUDA version the host's driver supports, when the provider says.
     cuda_max: Optional[float] = None
+    # The GPU's compute capability (architecture), e.g. 8.6 for an RTX 3090,
+    # when the provider says. Distinct from cuda_max (the driver's CUDA).
+    compute_cap: Optional[float] = None
     # The physical machine behind the offer, when the provider says. Offers
     # on one machine share its network, disk and Docker daemon.
     host_id: Optional[str] = None

jambu_gpu-0.3.1/jambu_gpu/core/paths.py

@@ -0,0 +1,42 @@
+"""Where gpu keeps its files: ``.gpu/`` in a project, ``~/.gpu`` per user.
+
+Both were named ``.jambu`` before 0.3.0. A legacy directory is renamed in
+place the first time it is needed, so an instance a project already tracks
+is never forgotten (and never rented twice) after an upgrade.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+STATE_DIRNAME = ".gpu"
+LEGACY_STATE_DIRNAME = ".jambu"
+
+
+def adopt_legacy(path: Path, legacy: Path) -> Path:
+    """``path``, after moving ``legacy`` there when only the legacy one exists."""
+    if not path.exists() and legacy.is_dir():
+        try:
+            legacy.rename(path)
+        except OSError:
+            # Read-only or racing another gpu process: keep using the old one.
+            return path if path.exists() else legacy
+    return path
+
+
+def project_state_dir(project_dir: Path) -> Path:
+    project_dir = Path(project_dir)
+    return adopt_legacy(project_dir / STATE_DIRNAME, project_dir / LEGACY_STATE_DIRNAME)
+
+
+def gpu_home() -> Path:
+    """Per-user files: the project registry, sweep sightings, bad hosts, credentials.
+
+    ``$GPU_HOME`` overrides it (``$JAMBU_HOME`` is still honored).
+    """
+    override = os.environ.get("GPU_HOME") or os.environ.get("JAMBU_HOME")
+    if override:
+        return Path(override).expanduser()
+    home = Path.home()
+    return adopt_legacy(home / STATE_DIRNAME, home / LEGACY_STATE_DIRNAME)

{jambu_gpu-0.2.0 → jambu_gpu-0.3.1}/jambu_gpu/core/state.py

@@ -1,6 +1,6 @@
 """Observed runtime state (spec section 9).
 
-jambu.yaml is the desired-state SoT; ``.jambu/state.json`` is what we last
+jambu.yaml is the desired-state SoT; ``.gpu/state.json`` is what we last
 observed. This module owns reading/writing it atomically, plus the on-disk
 process lock that keeps two CLI invocations from provisioning twice.
 """
@@ -312,7 +312,7 @@ class RuntimeState:
 
 
 class StateStore:
-    """Atomic reader/writer for ``.jambu/state.json``."""
+    """Atomic reader/writer for ``.gpu/state.json``."""
 
     def __init__(self, state_dir: Path) -> None:
         self._depth = 0  # flock is per-open-file-description: keep it reentrant

{jambu_gpu-0.2.0 → jambu_gpu-0.3.1}/jambu_gpu/core/sweep.py

@@ -4,7 +4,7 @@ The watchdog guards one instance from the inside and `gpu guard` guards the
 one instance a project tracks. The sweep covers every project on this machine
 and whatever is left over:
 
-- every project registered in ``$JAMBU_HOME/projects.json`` (by `gpu setup`)
+- every project registered in ``$GPU_HOME/projects.json`` (by `gpu setup`)
   gets its own ``Engine.guard_tick``, with its own config and state: its own
   max_lifetime, lock, session and stopped_ttl. Those instances are *tracked*;
 - an instance no project tracks is an *orphan*. Nobody knows its policy or
@@ -14,7 +14,7 @@ and whatever is left over:
   ago is destroyed.
 
 Providers do not report when an instance stopped, so the first time the sweep
-saw each orphan stopped is kept in ``$JAMBU_HOME/sweep.json``.
+saw each orphan stopped is kept in ``$GPU_HOME/sweep.json``.
 """
 
 from __future__ import annotations
@@ -30,7 +30,8 @@ from typing import Any, Callable, Iterator, Optional
 
 from . import events as ev
 from . import policy
-from .config import STATE_DIRNAME, load_config
+from .config import load_config
+from .paths import gpu_home, project_state_dir
 from .errors import JambuError, ProviderError
 from .events import EventLog
 from .models import Instance, InstanceState, is_jambu_label
@@ -46,8 +47,7 @@ SWEEP_ACTION = "sweep_action"
 
 
 def jambu_home() -> Path:
-    override = os.environ.get("JAMBU_HOME")
-    return Path(override).expanduser() if override else Path.home() / ".jambu"
+    return gpu_home()
 
 
 class SweepRegistry:
@@ -198,7 +198,7 @@ class ProjectGuard:
 
 def _state_beside(config_path: Path) -> Optional[RuntimeState]:
     """The project's state read straight from disk (no API call)."""
-    store = StateStore(Path(config_path).parent / STATE_DIRNAME)
+    store = StateStore(project_state_dir(Path(config_path).parent))
     try:
         return store.load() if store.exists() else None
     except JambuError:

{jambu_gpu-0.2.0 → jambu_gpu-0.3.1}/jambu_gpu/providers/vast/mapper.py

@@ -82,6 +82,12 @@ def _float_or_none(value: Any) -> Optional[float]:
         return None
 
 
+def _compute_cap(value: Any) -> Optional[float]:
+    """Vast's ``compute_cap`` is capability ×100 (860 → 8.6); normalize it."""
+    raw = _float_or_none(value)
+    return raw / 100.0 if raw else None
+
+
 def effective_min_cuda(spec: ComputeSpec, options: VastOptions) -> Optional[float]:
     """The stricter of the adapter's floor and what the spec (image) needs."""
     known = [
@@ -110,6 +116,8 @@ def map_offer(raw: dict[str, Any]) -> Offer:
         score=float(raw.get("score") or 0.0) if raw.get("score") is not None else None,
         # Highest CUDA the host driver runs; an image needing more dies at boot.
         cuda_max=_float_or_none(raw.get("cuda_max_good")),
+        # Vast reports compute capability ×100 (860 = 8.6); normalize to 8.6.
+        compute_cap=_compute_cap(raw.get("compute_cap")),
         host_id=host_id(raw),
         raw=raw,
     )
@@ -193,6 +201,12 @@ def build_search_query(
     min_cuda = effective_min_cuda(spec, options)
     if min_cuda:
         query["cuda_max_good"] = {"gte": min_cuda}
+    # Floor the GPU architecture, not just the driver's CUDA: Vast reports
+    # compute capability ×100, so 8.0 -> 800. Without this the cheapest offers
+    # (old Volta/Pascal cards behind modern drivers) pass cuda_max_good but
+    # crash a newer runtime image at engine startup.
+    if spec.gpu.compute_cap_min:
+        query["compute_cap"] = {"gte": int(round(float(spec.gpu.compute_cap_min) * 100))}
     # gpu_name is deliberately NOT sent server-side: Vast's field only
     # accepts an exact match ({"eq": ...}), but name_filter is documented and
     # used everywhere else (offer_matches below) as a case-insensitive
@@ -258,6 +272,10 @@ def offer_matches(offer: Offer, spec: ComputeSpec, min_cuda: Optional[float] = N
     # 1e-6: 12.9 must match a host reporting exactly 12.9.
     if min_cuda and offer.cuda_max is not None and offer.cuda_max + 1e-6 < min_cuda:
         return False
+    # Vast's compute_cap filter is advisory; verify the architecture floor too.
+    min_cc = spec.gpu.compute_cap_min
+    if min_cc and offer.compute_cap is not None and offer.compute_cap + 1e-6 < float(min_cc):
+        return False
     if offer.gpu_count < spec.gpu.count:
         return False
     if spec.gpu.min_vram_gb and offer.gpu_vram_gb + 0.5 < float(spec.gpu.min_vram_gb):

{jambu_gpu-0.2.0 → jambu_gpu-0.3.1}/jambu_gpu/runtime/base.py

@@ -116,6 +116,16 @@ class ModelRuntime(ABC):
         """
         return cuda_from_tag(image_tag(self.image()))
 
+    def required_compute_cap(self) -> Optional[float]:
+        """Minimum GPU compute capability (architecture) the runtime needs.
+
+        None if unknown. The offer filter is raised to this, so an image whose
+        kernels are built for newer architectures is never placed on a GPU too
+        old to run them (which the host driver's CUDA alone does not catch: a
+        Volta card behind a CUDA-13 driver still fails at engine startup).
+        """
+        return None
+
     # -- on-instance liveness -------------------------------------------------
 
     def runtime_pid_path(self) -> Optional[str]:

{jambu_gpu-0.2.0 → jambu_gpu-0.3.1}/jambu_gpu/runtime/vllm.py

@@ -123,6 +123,16 @@ class VllmRuntime(ModelRuntime):
     def required_cuda(self) -> Optional[float]:
         return vllm_image_cuda(self.image())
 
+    def required_compute_cap(self) -> Optional[float]:
+        # vLLM wheels built for CUDA 13+ drop Volta (sm_70) and need Ampere
+        # (8.0) or newer; those crash at engine-core init on a V100 or older.
+        # CUDA 12.x wheels still run Volta. Pascal (GTX 10xx, 6.1) is below
+        # vLLM's floor on any build.
+        cuda = self.required_cuda()
+        if cuda is None:
+            return None
+        return 8.0 if cuda >= 13.0 else 7.0
+
     def runtime_pid_path(self) -> str:
         return PID_PATH
 

{jambu_gpu-0.2.0 → jambu_gpu-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "jambu-gpu"
-version = "0.2.0"
+version = "0.3.1"
 description = "Provider-agnostic CLI for provisioning and managing temporary GPU runtimes"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -36,7 +36,7 @@ gpu = "jambu_gpu.cli.main:main"
 packages = ["jambu_gpu"]
 
 [tool.hatch.build.targets.sdist]
-exclude = ["/.env", "/.venv", "/.jambu"]
+exclude = ["/.env", "/.venv", "/.gpu", "/.jambu"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{jambu_gpu-0.2.0 → jambu_gpu-0.3.1}/tests/conftest.py

@@ -29,9 +29,10 @@ BASE_CONFIG = {
 
 @pytest.fixture(autouse=True)
 def jambu_home(tmp_path, monkeypatch):
-    """Keep the project registry and sweep state out of the real ~/.jambu."""
-    home = tmp_path / "jambu-home"
-    monkeypatch.setenv("JAMBU_HOME", str(home))
+    """Keep the project registry and sweep state out of the real ~/.gpu."""
+    home = tmp_path / "gpu-home"
+    monkeypatch.setenv("GPU_HOME", str(home))
+    monkeypatch.delenv("JAMBU_HOME", raising=False)
     return home
 
 

{jambu_gpu-0.2.0 → jambu_gpu-0.3.1}/tests/test_config.py

@@ -100,7 +100,7 @@ def test_fingerprint_tracks_runtime_identity(write_config):
 
 
 def test_state_dir_sits_next_to_the_config(config):
-    assert config.state_dir == config.source_path.parent / ".jambu"
+    assert config.state_dir == config.source_path.parent / ".gpu"
 
 
 # -- jambu.yaml shared-manifest namespacing ----------------------------------