gpu4agents 0.5.0__tar.gz

gpu4agents-0.5.0/.env.example

@@ -0,0 +1,11 @@
+# Credentials are resolved from the environment, this file, or
+# ~/.jambu/credentials - never from jambu.yaml.
+
+# Required by the vast provider.
+VAST_API_KEY=
+
+# Optional: needed for gated HuggingFace models.
+HF_TOKEN=
+
+# Optional: per-profile override, used when provider.profile: staging
+# VAST_API_KEY__staging=

gpu4agents-0.5.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,38 @@
+name: Bug report
+description: Something does not work as documented.
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: Never paste `VAST_API_KEY`, endpoint keys or `.env` contents. Security issues go to SECURITY.md, not here.
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened
+      description: What you ran, what you expected, what you got.
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: How to reproduce
+      description: The command or MCP tool call, and the relevant part of `jambu.yaml`.
+      render: shell
+  - type: textarea
+    id: output
+    attributes:
+      label: Output
+      description: "`gpu --json ...` output, the error and exit code, or `gpu logs --source onstart`."
+      render: text
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: "`gpu --version`"
+    validations:
+      required: true
+  - type: dropdown
+    id: surface
+    attributes:
+      label: How were you using it
+      options: [CLI, Claude Code, Cursor, Claude Desktop, Another MCP client, From an application]

gpu4agents-0.5.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Questions and ideas
+    url: https://github.com/jambuai/gpu4agents/discussions
+    about: Ask how to do something or share what you built.
+  - name: Security issue
+    url: https://github.com/jambuai/gpu4agents/security/advisories/new
+    about: Report a vulnerability privately.

gpu4agents-0.5.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,19 @@
+name: Feature request
+description: A provider, a runtime, a tool for agents, or something else.
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem
+      description: What are you or your agent trying to do, and what gets in the way?
+    validations:
+      required: true
+  - type: textarea
+    id: idea
+    attributes:
+      label: What you would like
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives you considered

gpu4agents-0.5.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: monthly

gpu4agents-0.5.0/.github/pull_request_template.md

@@ -0,0 +1,7 @@
+## What and why
+
+## How it was tested
+
+- [ ] `pytest` passes
+- [ ] Docs updated (README, `docs/`, `CHANGELOG.md`) if behavior changed
+- [ ] No key, token or `.env` content in the diff, tests or fixtures

gpu4agents-0.5.0/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+      - run: pip install -e ".[dev]"
+      - run: python -m pytest -q
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check dist/*

gpu4agents-0.5.0/.github/workflows/release.yml

@@ -0,0 +1,49 @@
+name: Release
+
+# Runs when a GitHub release is published: builds the wheel and sdist, attaches
+# them to the release, and publishes to PyPI with trusted publishing once the
+# repository variable PYPI_PUBLISH is "true" (see CONTRIBUTING.md, "Releasing").
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Check the tag matches the package version
+        run: |
+          version=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          test "v$version" = "${{ github.event.release.tag_name }}"
+      - run: pip install build twine && python -m build && twine check dist/*
+      - name: Attach to the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release upload "${{ github.event.release.tag_name }}" dist/* --clobber
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  pypi:
+    needs: build
+    if: vars.PYPI_PUBLISH == 'true'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

gpu4agents-0.5.0/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.gpu/
+.jambu/
+.env
+.env.*
+!.env.example
+.pytest_cache/
+.coverage
+node_modules/
+*.tsbuildinfo
+.claude/
+
+# Cloudflare wrangler cache
+.wrangler/

gpu4agents-0.5.0/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to this project. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses [Semantic Versioning](https://semver.org/).
+
+## [0.5.0] - 2026-11-02
+
+### Changed
+- **Renamed to GPU for Agents.** The package is now `gpu4agents` on PyPI (it was `jambu-gpu`) and the module is `gpu4agents`. The `gpu` command, the MCP server and tool names, `jambu.yaml`, `.gpu/`, `~/.gpu` and the labels on running instances are unchanged, so existing projects and machines keep working.
+- The repository moved to [jambuai/gpu4agents](https://github.com/jambuai/gpu4agents); the old URLs redirect.
+- New website: [gpu4agents.jambu.ai](https://gpu4agents.jambu.ai).
+
+### Added
+- `gpu --version` (same as `gpu version`).
+
+### Migrating
+- `pipx uninstall jambu-gpu && pipx install gpu4agents` (or `uv tool install gpu4agents`).
+- A `jambu_gpu` alias module ships with the package, so sweep timers that run `python -m jambu_gpu sweep --apply` keep working; `gpu sweep --install-timer` rewrites them for `gpu4agents`.
+- `jambu-gpu` 0.5.0 on PyPI is a transition release that installs `gpu4agents`.
+
+## [0.4.1] - 2026-10-25
+
+### Fixed
+- A stalled image pull no longer costs 30 minutes per host. `gpu setup` replaces a host whose pull shows no progress for `health.pull_stall_timeout` (default `10m`; `off` disables it). The host is destroyed, remembered as bad for 24h, and another is rented. A host that pulls slowly but steadily still waits for `boot_timeout`.
+
+## [0.4.0] - 2026-10-25
+
+### Added
+- `gpu mcp`: a local MCP server (stdio) with 13 tools, from `gpu_init` to `gpu_destroy`. `gpu_setup` runs in the background and re-attaches on each call, so a long first rent never hits a tool timeout.
+- A bundled skill that tells the agent to show the price and ask before renting, wait out a slow setup, never touch `VAST_API_KEY`, and clean up.
+- `gpu agent install` (`-t claude | cursor | desktop`, `--global`) writes the skill and registers the server.
+
+### Fixed
+- `gpu status` and `gpu logs` work during a setup (`"busy": true`); a held project lock is exit code 12.
+- The last host that failed when setup gave up is remembered as bad.
+- On Vast the vLLM image defaults to `vastai/vllm:v0.32.0-cuda-13.0`, cached on Vast hosts.
+
+## [0.3.1] - 2026-10-25
+
+### Fixed
+- Vast: floor the GPU compute capability (vLLM: 8.0 on CUDA-13 images, 7.0 on CUDA-12), overridable with `compute.gpu.compute_cap_min`, so old cards behind a new driver are no longer rented.
+
+## [0.3.0] - 2026-10-24
+
+### Changed
+- Files live in `.gpu/` (per project) and `~/.gpu` (per user) instead of `.jambu`. The first command renames the old directories. `GPU_HOME` overrides `~/.gpu`.
+
+## [0.2.0] - 2026-10-24
+
+### Added
+- The watchdog retries a failed stop, re-arms on every restart and runs under a supervisor; inference traffic counts as activity; stopped instances are destroyed after `lifecycle.stopped_ttl`.
+- `gpu ls` and `gpu sweep` (with a systemd timer) guard every project and clean up orphans.
+- A per-instance endpoint key; `gpu --json setup` / `gpu env` return `base_url`, `api_key` and `model`.
+- [docs/INTEGRATION.md](docs/INTEGRATION.md) and a one-file TypeScript client.
+
+[0.5.0]: https://github.com/jambuai/gpu4agents/compare/v0.4.1...v0.5.0
+[0.4.1]: https://github.com/jambuai/gpu4agents/compare/v0.4.0...v0.4.1
+[0.4.0]: https://github.com/jambuai/gpu4agents/compare/v0.3.1...v0.4.0
+[0.3.1]: https://github.com/jambuai/gpu4agents/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/jambuai/gpu4agents/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/jambuai/gpu4agents/releases/tag/v0.2.0

gpu4agents-0.5.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,84 @@
+
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at joao.gabriel@jambu.ai. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

gpu4agents-0.5.0/CONTRIBUTING.md

@@ -0,0 +1,81 @@
+# Contributing
+
+`gpu4agents` provisions a temporary GPU runtime and guarantees it stops billing
+when nothing is using it. Contributions are welcome. By submitting a change you
+agree it is licensed under the [MIT License](LICENSE).
+
+## Command name
+
+The published command is `gpu`. The package is `gpu4agents` (published as `jambu-gpu` before 0.5.0).
+
+Do not add a second console script. One command, in `pyproject.toml`:
+
+```toml
+[project.scripts]
+gpu = "gpu4agents.cli.main:main"
+```
+
+## Setup
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+```
+
+Python 3.10 or newer. Tests do not need `VAST_API_KEY`, a GPU, or network access.
+
+## Tests
+
+```bash
+.venv/bin/pytest
+.venv/bin/pytest tests/test_policy.py       # shutdown rule
+.venv/bin/pytest tests/test_watchdog.py     # generated guard, as a real process
+.venv/bin/pytest tests/test_integration.py  # setup -> boot -> run -> auto-stop
+```
+
+A change to lifecycle behaviour needs a test that fails before the change and
+passes after it. The policy in `gpu4agents/core/policy.py` and the watchdog that
+runs on the instance must keep agreeing: the watchdog inlines that module at
+provision time.
+
+`tests/test_integration.py` does not mock the boot. It runs the onstart script
+the engine generated, starts the real watchdog, waits on a real health endpoint,
+runs a workload with real heartbeats, and asserts the guard stops the instance
+with the right reason.
+
+## What you may change
+
+| Change | Where it goes |
+| --- | --- |
+| New provider | `gpu4agents/providers/<name>/` plus one registry line. See [docs/ADDING_A_PROVIDER.md](docs/ADDING_A_PROVIDER.md). |
+| Shutdown rule | `gpu4agents/core/policy.py` and `tests/test_policy.py`. |
+| How the model server starts | `gpu4agents/runtime/`. |
+| CLI surface | `gpu4agents/cli/`. Keep `--json` and `--config` on every command. |
+
+The core must not branch on a provider name. Branch on `provider.capabilities`.
+If a provider feature requires an `if provider == "..."` in `core/`, the contract
+is wrong — extend the contract instead.
+
+Out of scope: multi-instance scheduling, multi-GPU
+orchestration, Kubernetes, distributed inference, automatic provider selection,
+job queues, a web dashboard. See [docs/ACCEPTANCE.md](docs/ACCEPTANCE.md).
+
+## Secrets
+
+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 `~/.gpu/credentials`. `.env.example` ships with empty values only.
+
+## Pull requests
+
+- Explain why the behaviour should change, not only what moved.
+- Run `.venv/bin/pytest` and report the result.
+- Keep commits focused. A provider adapter and a policy change are two PRs.
+- Match the surrounding style: English identifiers and docs, type hints on new
+  public functions, no new dependency unless the standard library cannot do the job.
+
+## Releasing
+
+1. Bump `version` in `pyproject.toml` and `gpu4agents/__init__.py`, and add the entry to `CHANGELOG.md`.
+2. Merge to `main`, tag `vX.Y.Z` and publish a GitHub release with the changelog entry as notes.
+3. The `Release` workflow builds the wheel and sdist, checks the tag matches the version, and attaches them to the release. With the repository variable `PYPI_PUBLISH=true` and a PyPI trusted publisher for this repository (workflow `release.yml`, environment `pypi`), it also publishes to PyPI.

gpu4agents-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jambu.ai and João Gabriel Lima
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gpu4agents-0.5.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.5
+Name: gpu4agents
+Version: 0.5.0
+Summary: GPU for Agents: your coding agent rents the GPU it needs, on its own. You pay only while it works.
+Project-URL: Homepage, https://gpu4agents.jambu.ai
+Project-URL: Documentation, https://github.com/jambuai/gpu4agents/tree/main/docs
+Project-URL: Repository, https://github.com/jambuai/gpu4agents
+Project-URL: Issues, https://github.com/jambuai/gpu4agents/issues
+Project-URL: Changelog, https://github.com/jambuai/gpu4agents/blob/main/CHANGELOG.md
+Project-URL: Author, https://www.linkedin.com/in/joaogabriellima
+Author: Jambu.ai
+Author-email: João Gabriel Lima <joao.gabriel@jambu.ai>
+License: MIT
+License-File: LICENSE
+Keywords: agents,claude-code,cost,cursor,gpu,inference,llm,mcp,vast-ai,vllm
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+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: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.6.0
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: rich>=13.7.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: respx>=0.21.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <a href="https://gpu4agents.jambu.ai">
+    <img src="docs/assets/banner.png" alt="GPU for Agents: your agent rents the GPU it needs, on its own. You pay only while it works." width="100%">
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/gpu4agents/"><img src="https://img.shields.io/pypi/v/gpu4agents?color=5CBF3A&label=pypi" alt="PyPI"></a>
+  <a href="https://pypi.org/project/gpu4agents/"><img src="https://img.shields.io/pypi/pyversions/gpu4agents?color=5CBF3A" alt="Python versions"></a>
+  <a href="https://github.com/jambuai/gpu4agents/actions/workflows/ci.yml"><img src="https://github.com/jambuai/gpu4agents/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-5CBF3A" alt="MIT license"></a>
+</p>
+
+<p align="center">
+  <a href="https://gpu4agents.jambu.ai">Website</a> ·
+  <a href="https://gpu4agents.jambu.ai/#video">1-minute video</a> ·
+  <a href="docs/AGENTS.md">Agents guide</a> ·
+  <a href="https://github.com/jambuai/gpu4agents/wiki">Wiki</a> ·
+  <a href="CHANGELOG.md">Changelog</a>
+</p>
+
+# GPU for Agents
+
+**Your agent rents the GPU it needs, on its own.**
+**You pay only while it works: we watch every machine and shut down the idle ones.**
+
+Ask Claude Code, Cursor or any MCP client to "compare Qwen 7B and Llama 8B on these 50 prompts". The agent finds a GPU under your budget, serves the model behind an OpenAI-compatible API with vLLM, and runs the experiment. A watchdog runs on the machine itself, so when nothing uses it for `idle_timeout` (15 minutes by default) it shuts down, even if the agent forgot, the chat closed or your laptop is asleep.
+
+- **Self-service GPUs for agents.** A skill and local MCP tools (`gpu_offers`, `gpu_setup`, `gpu_run`, `gpu_status`, `gpu_destroy`, ...) give the agent the whole lifecycle. The skill tells it to show you the price and ask before renting.
+- **Billing that ends when the work does.** Idle timeout, maximum lifetime, hourly and session budgets, and a sweep that cleans up anything left behind.
+- **Any app, any language.** `gpu --json setup` returns `base_url`, `api_key` and `model` for any OpenAI SDK.
+
+Vast.ai is the first provider; another provider is a new adapter, and the lifecycle rule stays the same.
+
+## Quickstart: give your agent a GPU
+
+```bash
+pipx install gpu4agents            # or: uv tool install gpu4agents
+cd your-project
+echo "VAST_API_KEY=..." >> .env    # or ~/.gpu/credentials; never in jambu.yaml
+gpu agent install                  # Claude Code; -t cursor, -t desktop, --global
+```
+
+Then ask the agent for an experiment. See [Letting a coding agent rent GPUs](docs/AGENTS.md).
+
+## Quickstart: from a shell or an app
+
+```bash
+gpu init --model Qwen/Qwen2.5-7B-Instruct
+gpu validate
+gpu offers                         # see prices, rent nothing
+gpu setup                          # rent, boot vLLM, wait until the model answers
+gpu run python experiment.py       # OPENAI_BASE_URL / OPENAI_API_KEY are set for the job
+gpu destroy                        # or walk away: the idle timeout does it
+```
+
+From an application in any language, `gpu --json setup` prints the endpoint as JSON. See [Integrating into an application](docs/INTEGRATION.md), with a ready TypeScript client.
+
+## Declare the limits
+
+```yaml
+# jambu.yaml (only the gpu_runtime key is read, so other Jambu tools can share the file)
+gpu_runtime:
+  provider: {name: vast}
+  model_profile: qwythos-9b
+  lifecycle:
+    idle_timeout: 15m          # the watchdog on the machine stops it
+    max_lifetime: 6h           # a hard ceiling, busy or not
+  budget:
+    max_hourly_cost_usd: 0.60  # offers above this are never rented
+    max_session_cost_usd: 5.00
+  health:
+    pull_stall_timeout: 10m    # a host whose image pull stalls is replaced
+```
+
+A full example is [`jambu.example.yaml`](jambu.example.yaml). As a last line of defense, `gpu ls` shows every machine billing in the account and `gpu sweep --install-timer` guards every project on the machine and cleans up orphans. 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, and the agent never sees it.
+
+## Docs
+
+- [Letting a coding agent rent GPUs (Claude Code, Cursor, Claude Desktop)](docs/AGENTS.md)
+- [Integrating into an application (any language)](docs/INTEGRATION.md)
+- [Commands, workloads, and agents](docs/USAGE.md)
+- [Every config field](docs/CONFIG.md)
+- [Choosing a model](docs/CHOOSING_A_MODEL.md)
+- [How shutdown works](docs/LIFECYCLE.md)
+- [Adding a provider](docs/ADDING_A_PROVIDER.md)
+
+## Coming from `jambu-gpu`
+
+The package was called `jambu-gpu` until 0.4.1. Same code, same `gpu` command, same `jambu.yaml`, same machines:
+
+```bash
+pipx uninstall jambu-gpu && pipx install gpu4agents
+```
+
+Sweep timers installed by `jambu-gpu` keep working; `gpu sweep --install-timer` rewrites them for the new module.
+
+## Contributing
+
+Issues and pull requests are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md). Report security issues privately, as described in [SECURITY.md](SECURITY.md).
+
+## Author
+
+Created by [João Gabriel Lima](https://www.linkedin.com/in/joaogabriellima) at [Jambu.ai](https://jambu.ai).
+
+## License
+
+[MIT](LICENSE).
+
+<p align="center">
+  <a href="https://jambu.ai">
+    <img src="docs/assets/jambu-logo.jpg" alt="Jambu.ai — Applied Intelligence Lab" width="240">
+  </a>
+</p>