diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
new file mode 100644
index 0000000..9990586
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,60 @@
+name: Bug report
+description: Something in the SDK, the drums command or the MCP server does not behave as documented.
+labels: ["bug"]
+body:
+ - type: markdown
+ attributes:
+ value: |
+ Thanks for the report. Do not paste an API key anywhere in this issue; if one was exposed, revoke it first.
+ Security problems go through private reporting, not an issue: see SECURITY.md.
+ - type: textarea
+ id: what
+ attributes:
+ label: What happened
+ description: What you did, what you expected, what you got instead.
+ validations:
+ required: true
+ - type: textarea
+ id: repro
+ attributes:
+ label: Smallest script or command that shows it
+ description: Python or shell, as pasted. Replace the key with drums_sk_...
+ render: python
+ validations:
+ required: true
+ - type: textarea
+ id: error
+ attributes:
+ label: Error output
+ description: The full traceback or the error text. Gateway errors carry a request_id (gw_...); include it.
+ render: text
+ - type: input
+ id: version
+ attributes:
+ label: SDK version
+ description: Output of `drums version` or `python -c "import drums; print(drums.__version__)"`
+ placeholder: drums 0.3.0
+ validations:
+ required: true
+ - type: input
+ id: python
+ attributes:
+ label: Python version and OS
+ placeholder: Python 3.12.5, macOS 15 / Ubuntu 24.04
+ validations:
+ required: true
+ - type: dropdown
+ id: server
+ attributes:
+ label: Server
+ options:
+ - Drums Cloud (beta.drums.run)
+ - self-hosted drumsd
+ - the fake gateway in tests
+ validations:
+ required: true
+ - type: input
+ id: runtime
+ attributes:
+ label: Runtime version
+ description: Output of `client.health()["version"]`, if you can reach the server.
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000..89b7b7e
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,11 @@
+blank_issues_enabled: true
+contact_links:
+ - name: Security report
+ url: https://github.com/Drums-Labs/drums-python-sdk/security/advisories/new
+ about: Report a vulnerability privately. Please do not open a public issue for it.
+ - name: Documentation
+ url: https://console.drums.run/docs
+ about: Quickstart, concepts, the SDK reference and the HTTP API.
+ - name: Account, billing or a problem with your workspace
+ url: https://console.drums.run
+ about: Workspace questions go through the console, not this repository.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
new file mode 100644
index 0000000..daf693b
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,36 @@
+name: Feature request
+description: A method, option, tool or behaviour you need from the SDK or the MCP server.
+labels: ["enhancement"]
+body:
+ - type: textarea
+ id: problem
+ attributes:
+ label: What you are trying to do
+ description: The workflow, not the solution. What do you do today instead?
+ validations:
+ required: true
+ - type: textarea
+ id: proposal
+ attributes:
+ label: What you would like
+ description: The call, option or tool as you would write it. Pseudo-code is fine.
+ render: python
+ validations:
+ required: true
+ - type: dropdown
+ id: area
+ attributes:
+ label: Area
+ options:
+ - Python client (drums, drums.aio)
+ - MCP server or drums command
+ - hybrid tools (shell, files, office, browser)
+ - errors and validity
+ - packaging or docs
+ validations:
+ required: true
+ - type: textarea
+ id: context
+ attributes:
+ label: Anything else
+ description: Links to the docs page or the gateway route involved, if you know them.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000..3ba42f2
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,20 @@
+## What changed
+
+
+
+## How it was tested
+
+
+
+```bash
+python3 -m unittest discover -s tests -v
+```
+
+## Checklist
+
+- [ ] Tests added or updated for the behaviour that changed, including the error path
+- [ ] `CHANGELOG.md` updated under the next version heading
+- [ ] Docstrings say what the method sends, returns and raises
+- [ ] No third-party runtime dependency added
+- [ ] No tokens, keys, private hostnames or account identifiers in code, tests, fixtures or docs
+- [ ] Commits are signed off (`git commit -s`, see CONTRIBUTING.md)
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
new file mode 100644
index 0000000..e196272
--- /dev/null
+++ b/.github/dependabot.yml
@@ -0,0 +1,16 @@
+version: 2
+updates:
+ # The package has no runtime dependencies; this covers the build backend pinned in pyproject.toml.
+ - package-ecosystem: pip
+ directory: /
+ schedule:
+ interval: weekly
+ labels: ["dependencies"]
+ - package-ecosystem: github-actions
+ directory: /
+ schedule:
+ interval: weekly
+ labels: ["dependencies"]
+ groups:
+ actions:
+ patterns: ["*"]
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 01633cc..69b32d1 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -14,7 +14,7 @@ jobs:
strategy:
fail-fast: false
matrix:
- python: ["3.9", "3.12", "3.13"]
+ python: ["3.9", "3.10", "3.11", "3.12", "3.13"]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 0000000..42a1bcb
--- /dev/null
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,135 @@
+# 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: the maintainers
+of the Drums-Labs organization on GitHub. A private report through the
+repository's
+[security advisories page](https://github.com/Drums-Labs/drums-python-sdk/security/advisories/new)
+reaches them too; mark it "code of conduct".
+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
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c43146b..2cd0224 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,14 +1,15 @@
# Contributing to drums-sdk
-Thanks for helping. This package is the Python client for Drums; it uses only the standard library and supports
-Python 3.9 and later.
+Thanks for helping. This package is the Python client and MCP server for Drums; it uses only the standard library
+and supports Python 3.9 and later. By taking part you agree to the [code of conduct](CODE_OF_CONDUCT.md).
## Set up
```bash
git clone https://github.com/Drums-Labs/drums-python-sdk.git
cd drums-python-sdk
-python3 -m venv .venv && .venv/bin/pip install -e .
+python3 -m venv .venv
+.venv/bin/pip install -e .
```
## Run the tests
@@ -17,29 +18,62 @@ python3 -m venv .venv && .venv/bin/pip install -e .
.venv/bin/python -m unittest discover -s tests -v
```
-The tests run against a fake daemon on 127.0.0.1 and need no Drums account. Run them on the oldest Python you have
-as well as the newest; CI covers 3.9 through 3.13.
+The tests run against a fake gateway on `127.0.0.1` and need no Drums account or network. CI runs them on Python
+3.9 through 3.13; run them on the oldest and the newest Python you have. If `uv` is installed, the whole matrix is:
+
+```bash
+for v in 3.9 3.10 3.11 3.12 3.13; do uv run --python "$v" --no-project python -m unittest discover -s tests; done
+```
+
+CI also builds the package and checks it:
+
+```bash
+.venv/bin/pip install --upgrade build twine
+.venv/bin/python -m build
+.venv/bin/python -m twine check --strict dist/*
+```
## Make a change
-- Keep the package dependency-free. A change that needs a third-party library needs a discussion first.
+- Keep the package dependency-free. A change that needs a third-party library needs a discussion in an issue first.
- Every public method gets a docstring that says what it sends, what it returns and which `drums.errors` it raises.
- Add or update a test in `tests/` for the behaviour you change, including the error path.
+- A change to `drums/mcp_tools.json` must keep the list identical to the one the gateway serves; say in the PR which
+ gateway change it pairs with.
- Update `CHANGELOG.md` under the next version heading.
-- Do not put tokens, keys, hostnames of private machines or prices in code, tests, fixtures or docs.
+- Do not put tokens, keys, hostnames of private machines, account identifiers or prices in code, tests, fixtures or
+ docs.
+
+## Sign your commits (DCO)
+
+Every commit needs a `Signed-off-by` line with your real name and email, which states that you wrote the change or
+have the right to submit it under the project's license, as set out in the
+[Developer Certificate of Origin](https://developercertificate.org/). Git adds it for you:
+
+```bash
+git commit -s -m "step: return the observation when screenshot=True"
+```
+
+To add it to the last commit:
+
+```bash
+git commit --amend -s --no-edit
+```
## Open a pull request
-- Small, focused PRs. One behaviour per PR.
-- Describe what changed and how you tested it. CI must be green.
-- Commit messages describe the change in plain words. No generated boilerplate or tool attribution lines.
+- Small, focused pull requests: one behaviour per PR.
+- Fill in the template: what changed, how you tested it. CI must be green.
+- Commit messages describe the change in plain words, in the present tense, with the area first
+ (`transport: ...`, `mcp: ...`, `tests: ...`). No generated boilerplate or tool attribution lines.
+- A maintainer reviews within a few days. We may ask for changes or for the PR to be split.
## Releases
-Maintainers cut releases by tagging `vX.Y.Z` on `main`; the release workflow builds the package, runs the tests on
-every supported Python and publishes to PyPI (see `RELEASE.md`).
+Maintainers cut releases by tagging `vX.Y.Z` on `main`; the release workflow builds the package, runs the tests
+against the built wheel on every supported Python and publishes to PyPI with Trusted Publishing (see
+[RELEASE.md](RELEASE.md)).
## Security
-Found a security problem? Do not open a public issue. Email the maintainers at the address on
-[drums.run](https://drums.run) and give us a few days to respond.
+Found a security problem? Do not open a public issue. Follow [SECURITY.md](SECURITY.md).
diff --git a/README.md b/README.md
index 1b9b9c1..d043064 100644
--- a/README.md
+++ b/README.md
@@ -1,221 +1,404 @@
-# drums-sdk
+
+
+
+
+
+
+
+
drums-python-sdk
+
+
+ Python SDK and MCP server for Drums: create, act on, fork, reset and verify isolated desktops for computer-use agents.
+
+
+## What it is
+
+Drums runs many isolated desktops on one host by sharing one running operating system and its applications while
+keeping each desktop's mutable state separate. A desktop (a *computer*) can be created from a template in seconds,
+acted on with GUI, shell and file actions, saved, forked into N copies of the same state, reset, and scored with a
+task's checker. Every episode carries a validity verdict, so a score from a broken environment never reaches training.
+
+This repository is the Python client for that runtime and the `drums` command. The package on PyPI is `drums-sdk`;
+the import name is `drums`. It uses only the standard library and supports Python 3.9 and later. It talks to Drums
+Cloud (`https://beta.drums.run/gw`) or to a self-hosted `drumsd` over the same HTTP API.
+
+## Install
-Python SDK for [Drums](https://drums.run): isolated desktop environments for computer-use agents and RL.
-Create a desktop, act in it, take screenshots, fork it into copies of the same state, and score it with a task's
-checker. Standard library only; Python 3.9 or later.
-
-Full documentation: **[console.drums.run/docs](https://console.drums.run/docs)**
+```bash
+pip install drums-sdk
+```
-## Five-minute start
+## Quickstart
-### 1. Install
+Sign in at [console.drums.run](https://console.drums.run), open **API Keys** and create a key. It starts with
+`drums_sk_` and is shown once. Then, in a terminal:
```bash
-python3 -m venv drums-venv
-drums-venv/bin/pip install drums-sdk
+export DRUMS_URL=https://beta.drums.run/gw
+export DRUMS_TOKEN=drums_sk_...
```
-The package on PyPI is `drums-sdk`; the import name is `drums`.
+Save this as `quickstart.py` and run it with `python quickstart.py`. It starts a desktop with OSWorld task
+`e0df059f` (rename a folder on the Desktop), saves a screenshot, performs one GUI action and one shell action, runs
+the task's checker and closes the desktop.
```python
import drums
+
+with drums.connect() as client: # reads DRUMS_URL and DRUMS_TOKEN
+ with client.create(task="e0df059f", ttl=900) as env: # OSWorld task id; ttl: lifetime in seconds
+ env.wait_valid() # every gate of this episode passed
+ open("screen.png", "wb").write(env.screenshot()) # PNG, 1920x1080
+ env.step("pyautogui.click(960, 540)") # GUI: pyautogui code runs inside the desktop
+ env.step({"type": "execute", "shell": True,
+ "command": "mv ~/Desktop/todo_list_Jan_1 ~/Desktop/todo_list_Jan_2"})
+ reward = env.verify(strict=False) # the task's checker plus the episode's validity
+ print("score", reward.score, "valid", reward.valid, reward.invalid_reasons)
+ print("computers left:", len(client.envs())) # 0: the with-block destroyed it
```
-### 2. Point it at your Drums
+Expected output:
-The SDK reads two environment variables. Your API key comes from **API Keys** in the
-[console](https://console.drums.run); it starts with `drums_sk_` and is shown once.
+```text
+score 1 valid True []
+computers left: 0
+```
-```bash
-export DRUMS_URL=https://beta.drums.run/gw # Drums Cloud gateway; or http://127.0.0.1:7070 for a local drumsd
-export DRUMS_TOKEN=drums_sk_... # your API key
+Use a score only when `valid` is `True`. With the default `strict=True`, `verify()` raises `drums.InvalidEpisode`
+for an invalid episode instead of returning a reward. A `401` raises `drums.AuthError`: the key is mistyped,
+revoked or expired. The full walkthrough is the [docs quickstart](https://console.drums.run/docs/quickstart).
+
+## How it works
+
+```mermaid
+flowchart LR
+ code["Your code drums, drums.aio, drums mcp"]
+ gw["Drums gateway beta.drums.run/gw"]
+ d["drumsd on a host one running OS"]
+ c1["computer"]
+ c2["computer"]
+ k1["child"]
+ k2["child"]
+ code -- "HTTPS + API key" --> gw
+ gw --> d
+ d --> c1
+ d --> c2
+ c1 -. "fork(2)" .-> k1
+ c1 -.-> k2
```
-The key is sent over HTTPS, or over plain HTTP to loopback only (`localhost`, `127.0.0.0/8`, `::1`). Any other
-`http://` URL raises `drums.InsecureTransport` before a request is made; `drums.connect(url, token,
-allow_insecure_http=True)` or `DRUMS_ALLOW_INSECURE_HTTP=1` opts in.
+The SDK is a thin client of the gateway's `/v1` routes ([HTTP API](https://console.drums.run/docs/reference/http-api)).
+A `Client` creates computers and lists them; an `Env` is one computer: it steps, screenshots, saves, forks, resets
+and verifies. Names differ between the SDK and the raw API: a computer is a *slot*, a saved state a *checkpoint*,
+save is *capture* and fork is *branch*. They are the same things.
+
+- **Cleanup.** `with drums.connect() as client:` closes every computer the client created when the block ends, and so
+ do process exit and SIGTERM/SIGHUP. Computers and saved states also have server-side leases (default: reaped after
+ 30 minutes unused), so a crashed trainer does not hold a host.
+- **Validity.** Every episode starts with a gate report (isolation, mounts, network, limits, state hash, processes
+ alive after resume). `Reward.valid` is `True` only when every gate passed and the computer was never quarantined.
+- **Retries.** GET requests are retried while the server is unreachable (up to `retry_s`, default 60 s). POST and
+ DELETE are never retried: after a lost reply the outcome is unknown, so check `client.envs()` before trying again.
-Check the connection:
+## Computers
```python
import drums
-client = drums.connect() # reads DRUMS_URL and DRUMS_TOKEN
-print(client.health()["version"])
-```
-
-A `401` raises `drums.AuthError`: the key is mistyped, revoked or expired.
+client = drums.connect()
-### 3. Create a computer, screenshot, act, verify, destroy
+env = client.create(task="e0df059f", ttl=900) # from the default template, with an OSWorld task
+env = client.create(image="osworld-ubuntu") # a template, no task; env.load_task(...) later
+envs = client.create_many(8, task="e0df059f") # 8 computers created concurrently
-Save as `quickstart.py` and run `drums-venv/bin/python quickstart.py`. It starts a desktop with OSWorld task
-`e0df059f` (rename a folder on the Desktop), waits until every gate of the episode has passed, saves a screenshot,
-performs the task with one action, runs the task's checker and closes the desktop.
+state = env.save() # a saved state; the computer keeps running
+again = client.create(from_state=state) # a new computer from that state
+client.delete_state(state) # once no computer uses it
-```python
-import drums
+kids = env.fork(4, keep_state=False) # 4 children from this exact state; the parent keeps running
+print(kids.state, [k.id for k in kids]) # the state the fork made, and the children
+kids.close() # close all children
-with drums.connect() as client: # closes every desktop it created when the block ends
- with client.create(task="e0df059f", ttl=900) as env: # OSWorld task id; ttl: lifetime in seconds
- env.wait_valid() # every gate of this episode passed
- obs = env.observe() # PNG screenshot plus metadata
- open("screen.png", "wb").write(obs.png)
- print("task:", obs.meta["instruction"])
- env.step({"type": "execute", "shell": True,
- "command": "mv ~/Desktop/todo_list_Jan_1 ~/Desktop/todo_list_Jan_2"})
- reward = env.verify(strict=False) # the task's checker, with the episode's validity
- print("score", reward.score, "valid", reward.valid, reward.invalid_reasons)
- print("computers left:", len(client.envs())) # 0: the with-block destroyed it
+env.reset() # back to the template or saved state; the task's setup runs again
+env.close() # destroy; a no-op if it is already gone
```
-Expected output (ids and sizes differ):
+`create` takes `idle_timeout` and `ttl` (seconds) for the computer's lease; `fork` and `save` take the same for
+the children and the state. `fork` captures the state right after an action without a sleep: it waits until the
+process tree is quiescent and raises `drums.NotQuiescent` if it cannot within `quiesce_timeout`. `env.prefork(n)`
+prepares the next fork in the background. Guides: [snapshots and forks](https://console.drums.run/docs/concepts/snapshots-and-forks),
+[group rollouts with fork](https://console.drums.run/docs/guides/group-rollouts-with-fork).
-```text
-task: I have a directory named "todo_list_Jan_1". Can you help me change its name into "todo_list_Jan_2"?
-score 1 valid True []
-computers left: 0
+## Actions
+
+`env.step(action)` runs one action inside the desktop as its user (not root) and returns a `StepResult`. The screen
+is 1920x1080 with the origin top left.
+
+```python
+env.step("pyautogui.click(100, 200)") # a str is pyautogui code
+env.step("pyautogui.write('hello'); pyautogui.hotkey('ctrl', 's')")
+env.step({"type": "execute", "shell": True, "command": "ls ~/Desktop"}) # a shell command, waits for it
+env.step({"type": "launch", "shell": True, "command": "gedit &"}) # start a program, do not wait
+env.step({"type": "sleep", "seconds": 2})
+
+r = env.step("pyautogui.click(960, 540)", screenshot=True) # the screenshot after the action
+r.observation.png # PNG bytes
+r = env.step({"type": "execute", "command": "test -f ~/x", "shell": True}, check=False)
+r.result["returncode"] # 1 here; check=True would raise ActionFailed
```
-A GUI agent acts with pyautogui instead of a shell command: `env.step("pyautogui.click(960, 540)")`.
-Use a score only when `valid` is `True`; with the default `strict=True`, `verify()` raises `InvalidEpisode`
-for an invalid episode instead of returning a reward.
+An action that ran and exited non-zero raises `drums.ActionFailed` (with `returncode`, `output`, `error`);
+`check=False` returns the result instead. `env.observe()` returns an `Observation` (PNG plus task, episode and
+verdict metadata). `drums.hybrid.HybridTools(env)` adds `shell`, `read_file`, `write_file`, `list_dir`,
+`office_convert`, `spreadsheet_read`, `browser_tabs` and `browser_open` over the same computer, with `TOOLS` as
+their JSON schema. Reference: [actions](https://console.drums.run/docs/concepts/computers-and-templates#actions).
-### 4. Go further
+## Verify and the `trusted` flag
-- Fork one desktop into N copies of the same state for group rollouts: `with env.fork(8) as kids: ...`
- ([guide](https://console.drums.run/docs/guides/group-rollouts-with-fork))
-- Run a policy over many tasks: [Evaluate on OSWorld](https://console.drums.run/docs/guides/evaluate-on-osworld)
-- `drums.aio` is the asyncio variant of the same calls; `drums.hybrid` adds shell, file and app-API tools over one
- desktop; `drums mcp` serves the whole workflow to an agent over MCP (stdio), see [MCP server](#mcp-server).
-- Every method: [Python SDK reference](https://console.drums.run/docs/reference/python-sdk).
- Every endpoint: [HTTP API](https://console.drums.run/docs/reference/http-api).
- If something fails: [Errors](https://console.drums.run/docs/reference/errors).
+```python
+reward = env.verify(strict=False)
+reward.score # the checker's score (1 or 0 for OSWorld tasks), None if the checker did not run
+reward.valid # True only when every gate of the episode passed and the computer was never quarantined
+reward.invalid_reasons # why not, in words (empty when valid)
+reward.trusted # True, False or None (see below)
+reward.audit_flags # e.g. ["scope"], ["checker_timeout"]
+```
-## How it behaves
+`valid` is about the environment; `trusted` is about the reward. After the checker runs, drumsd audits the result
+(a recheck, a redundant checker where one exists, a scope check that flags reward hacking, checker timeout or crash).
+`trusted` is `True` only for a valid episode with a score and no audit flag. It is `False` when a flag was raised and
+`None` when the server sent no audit (an older runtime), never `True` by default. Train on `score` when `valid` is
+`True`; prefer `trusted` when it is available.
-- **Cleanup.** `with drums.connect() as client:` closes every desktop the client created when the block ends, and so
- do process exit and SIGTERM/SIGHUP. Desktops and saved states also have server-side leases (default: reaped after
- 30 minutes unused), so a crashed trainer does not hold a host.
-- **Validity.** Every episode starts with a gate report (isolation, mounts, network, limits, state hash, processes
- alive after resume). `Reward.valid` is `True` only when every gate passed and the desktop was never quarantined.
-- **Retries.** GET requests are retried while the server is unreachable (up to `retry_s`, default 60 s). POST and
- DELETE are never retried: after a lost reply the outcome is unknown, so check `client.envs()` before trying again.
-- **Errors.** Every failure is a typed exception under `drums.DrumsError` carrying the server's status, message and
- body; errors about a desktop carry its record and gate report.
+With `strict=True` (the default), `verify()` raises `drums.InvalidEpisode` for an invalid episode and
+`drums.CheckerError` when the checker failed; both carry the `Reward`. Tasks and checkers:
+[tasks and verifiers](https://console.drums.run/docs/concepts/tasks-and-verifiers).
-## MCP server
+## Runs
-`drums mcp` (the same as `python -m drums.mcp`) is an MCP server on stdio that gives an agent the whole workflow:
-start a computer, act in it, verify against a task checker, fork and reset it, and read run results. It talks to
-the Drums gateway (or a plain drumsd for the desktop tools) at `DRUMS_URL` with `DRUMS_TOKEN`.
+A run is a managed batch on the Drums gateway: a set of tasks played on desktops, every attempt verified and
+recorded, stopped at a spend or time cap. Runs are created in the console (**Runs > New run**); the SDK reads them
+and can submit the same request the wizard's review step shows.
-```
-drums mcp # all tools; desktop tools take computer_id
-drums mcp --env # desktop tools default to this computer
-drums mcp --create [--task FILE] # create one computer, bind it, close it on exit
-drums mcp --print-config claude|claude-local|cursor|codex
+```python
+page = client.runs(kind="scripted_test", status="completed", limit=20)
+for run in page["items"]:
+ print(run["id"], run["status"], run.get("stop_reason"))
+
+run = client.run(page["items"][0]["id"]) # status, counts and events of one run
+new = client.create_run(spec, idempotency_key="nightly-2026-11-13") # spec: the request the console shows
```
-The same tool list is served remotely by the gateway at `/mcp` (MCP Streamable HTTP, authenticated
-with a workspace API key; Drums MCP uses API keys, not OAuth). Replace `` with your workspace's gateway
-URL and `drums_sk_...` with a key from the console.
+Runs, evaluations, API keys and the audit log exist on the Drums gateway only; against a plain `drumsd` these
+methods raise `drums.NotFound`. Concepts: [runs and evaluations](https://console.drums.run/docs/concepts/runs-and-evaluations).
-Claude Code, remote:
+## MCP
-```
-claude mcp add --transport http drums /mcp --header "Authorization: Bearer drums_sk_..."
-```
+Drums publishes one MCP server with 34 tools: the workspace (computers, snapshots, tasks, runs, API keys, audit log)
+and the desktop itself (GUI, screenshot, shell, files, verify, fork, reset). Two ways to reach it:
-Claude Code, local (this package):
+| Transport | Where it runs | Address |
+|---|---|---|
+| Remote (Streamable HTTP) | inside the gateway | `https://beta.drums.run/gw/mcp` |
+| Local (stdio) | `drums mcp` from this package | your machine, talking to `DRUMS_URL` with `DRUMS_TOKEN` |
+Both list exactly the same tools with the same schemas (`drums/mcp_tools.json`). Authentication is the workspace
+API key in either case; there is no OAuth flow. `drums mcp --print-config` prints the snippet for each client with
+a placeholder key, never a real one:
+
+```bash
+export DRUMS_URL=https://beta.drums.run/gw
+drums mcp --print-config claude
```
-claude mcp add drums -e DRUMS_URL= -e DRUMS_TOKEN=drums_sk_... -- drums mcp
+
+```text
+claude mcp add --transport http drums https://beta.drums.run/gw/mcp --header "Authorization: Bearer drums_sk_..."
```
-Cursor (`~/.cursor/mcp.json` or `.cursor/mcp.json`):
+```bash
+drums mcp --print-config cursor # ~/.cursor/mcp.json or .cursor/mcp.json
+```
```json
-{"mcpServers": {"drums": {"url": "/mcp", "headers": {"Authorization": "Bearer drums_sk_..."}}}}
+{"mcpServers": {"drums": {"url": "https://beta.drums.run/gw/mcp", "headers": {"Authorization": "Bearer drums_sk_..."}}}}
```
-Codex (`~/.codex/config.toml`):
+```bash
+drums mcp --print-config codex # ~/.codex/config.toml; Codex starts the local server
+```
```toml
[mcp_servers.drums]
command = "drums"
args = ["mcp"]
-env = { DRUMS_URL = "", DRUMS_TOKEN = "drums_sk_..." }
+env = { DRUMS_URL = "https://beta.drums.run/gw", DRUMS_TOKEN = "drums_sk_..." }
```
-This repository is also a Claude Code plugin (`.claude-plugin/plugin.json`, `.mcp.json`, and the
-`drums-workflow` skill under `skills/`), which installs the server and a skill that teaches the loop below.
+`drums mcp --print-config claude-local` prints the Claude Code line for the local server. Replace `drums_sk_...`
+with your key. Treat the client's configuration file like a secret.
-### Tools
+The local server:
-Workspace tools (the gateway's HTTP API; `*` needs the Drums gateway and answers "not available on this server"
-against a plain drumsd):
+```bash
+drums mcp # all tools; desktop tools take computer_id
+drums mcp --env COMPUTER_ID # desktop tools default to this computer
+drums mcp --create # create one computer, bind it, close it on exit (--task FILE loads a task)
+```
-| tool | what it does |
-|---|---|
-| `list_templates` | base desktop images a computer can start from |
-| `list_computers`, `get_computer` | the workspace's computers: state, validity, task |
-| `create_computer` | a new computer from a template or snapshot, optionally with a task |
-| `destroy_computer` | close a computer for good (destructive) |
-| `list_snapshots`, `create_snapshot`, `delete_snapshot` | saved desktop states (delete is destructive) |
-| `list_tasks`, `get_task` | the verified computer-use tasks on the host |
-| `list_runs`, `create_run`, `get_run` * | runs: submit a RunSpec, read status, counts and events |
-| `list_evaluations`, `create_evaluation`, `get_evaluation` * | runs with kind `evaluation` |
-| `list_api_keys`, `create_api_key`, `revoke_api_key` * | API keys (metadata only; revoke is destructive) |
-| `read_audit_log` * | who did what, newest first; MCP calls appear as `mcp.` |
-
-Desktop tools (each takes `computer_id`):
-
-| tool | what it does |
+`drums mcp` is the same as `python -m drums.mcp`. The token comes from `DRUMS_TOKEN`, else the file named by
+`DRUMS_TOKEN_FILE`, else `/etc/drums/token`; it is never printed and never appears in an error message. This
+repository is also a Claude Code plugin (`.claude-plugin/plugin.json`, `.mcp.json`, the `drums-workflow` skill).
+
+Two rules:
+
+- **`confirm: true`.** `destroy_computer`, `delete_snapshot` and `revoke_api_key` (the tools marked `destructive`
+ in `mcp_tools.json`) are refused before any request is sent unless the tool arguments carry `confirm: true`. The
+ caller (the agent) supplies that argument; Drums does not prompt anyone. Whether a person approves the call is the
+ MCP client's job (Claude Code, Cursor and Codex each have tool-approval settings). `reset` discards a computer's
+ desktop state too, but it is not gated.
+- **HTTPS only.** The token travels over HTTPS, or over plain HTTP to loopback only (`localhost`, `127.0.0.0/8`,
+ `::1`, where a local `drumsd` listens). Any other `http://` URL in `--url` or `DRUMS_URL` is refused before a
+ request is sent (`drums.InsecureTransport`; exit 2 from `drums mcp`), with a message naming the host and the
+ opt-ins, never the token. To opt in: `drums mcp --allow-insecure-http`, `DRUMS_ALLOW_INSECURE_HTTP=1`, or
+ `drums.connect(url, token, allow_insecure_http=True)`. Redirects are followed only to the same origin, at most 5
+ hops, with the same check on every hop (`drums.RedirectRefused` otherwise).
+
+Tool list, scopes and examples: [MCP guide](https://console.drums.run/docs/guides/mcp).
+
+## Async client
+
+`drums.aio` offers the same calls as coroutines. Each `AsyncClient` has its own thread pool (default 1024 threads,
+started on demand), so N computers driven with `asyncio.gather` really run N calls at once.
+
+```python
+import asyncio
+
+import drums.aio
+
+
+async def main():
+ async with await drums.aio.connect() as client:
+ envs = await asyncio.gather(*[client.create(task="e0df059f") for _ in range(8)])
+ await asyncio.gather(*[e.step("pyautogui.click(960, 540)") for e in envs])
+ rewards = await asyncio.gather(*[e.verify(strict=False) for e in envs])
+ print([r.score for r in rewards if r.valid])
+
+
+asyncio.run(main())
+```
+
+## Errors
+
+Every failure is a typed exception under `drums.DrumsError` with `status` (the HTTP status, `0` when there was no
+reply), `message` and `body`. Errors about a computer carry its record and gate report.
+
+| Exception | When |
|---|---|
-| `gui` | pyautogui code in the desktop (1920x1080) |
-| `screenshot` | a PNG of the desktop (image content) |
-| `shell` | a bash command as the desktop user (no root, no internet) |
-| `read_file`, `write_file`, `list_dir` | the desktop's files (`~` is `/home/user`) |
-| `office_convert`, `spreadsheet_read` | LibreOffice conversions and sheet reads |
-| `browser_tabs`, `browser_open` | Chrome tabs through its DevTools port (1337) |
-| `load_task` | load a task into a running computer (setup runs, a new episode starts) |
-| `verify` | score the desktop with the task's checker: score, valid, trusted, audit flags |
-| `fork` | n children that continue from this exact state; the parent keeps running |
-| `reset` | back to the clean template state; the task's setup runs again |
-
-The canonical list with every input schema is `drums/mcp_tools.json`; `tools/list` returns exactly it, in order.
-
-### Safety
-
-- Gated tools need `confirm: true` from the caller. `destroy_computer`, `delete_snapshot` and `revoke_api_key`
- (the tools marked `destructive` in `mcp_tools.json`) are refused before any request is sent unless the tool
- arguments carry `confirm: true`. The caller (the agent) supplies that argument; Drums does not prompt anyone.
- Whether a person approves the call is the MCP client's job (Claude Code, Cursor and Codex each have their own
- tool-approval settings): there is no confirmation step inside Drums, and `confirm: true` from the caller is the
- only thing the server checks. `reset` also discards a computer's desktop state, but it is not gated.
-- The token only travels over HTTPS, or over plain HTTP to loopback (`localhost`, `127.0.0.0/8`, `::1`, where a
- local drumsd listens). With a token set, any other `http://` URL in `--url` or `DRUMS_URL` is refused before a
- request is sent, with a message naming the host and the opt-ins (never the token). To send the token over plain
- HTTP anyway, opt in: `drums mcp --allow-insecure-http`, `DRUMS_ALLOW_INSECURE_HTTP=1`, or
- `drums.connect(url, token, allow_insecure_http=True)` / `drums.Client(..., allow_insecure_http=True)` in the SDK
- (the `Client` applies the same rule, so SDK scripts are covered too; the error is `drums.InsecureTransport`).
-- Redirects are followed only to the same origin (scheme, host, port), at most 5 hops, with the same transport
- check on each hop; any other redirect raises `drums.RedirectRefused` before it is followed, so the token is
- never re-sent to another host or over plain HTTP because a server said `Location`.
-- Arguments are checked against the tool's schema before anything is sent; a violation is a tool error naming the
- field. A tool failure is always a tool result with `isError`, never a protocol error.
-- `--print-config` prints placeholders (`` when no URL is known, always `drums_sk_...`), never a key.
-- The token comes from `DRUMS_TOKEN`, else the file `DRUMS_TOKEN_FILE`, else `/etc/drums/token`; it is never
- printed or written by the server, and never appears in an error message.
-- Keys are workspace-scoped on the gateway: a key never sees another workspace's computers.
-- `create_api_key` returns the plaintext key once; nothing stores it.
+| `AuthError` | 401: missing, wrong, revoked or expired key |
+| `InsecureTransport` | refused before any request: a token would travel over plain HTTP off loopback |
+| `RedirectRefused` | refused: a redirect to another origin, or more than 5 hops |
+| `BadRequest` | 400 or 422: bad task JSON, bad id, `n` out of range |
+| `TaskUnsupported` | 422: the task needs the agent itself to act as root; nothing was started |
+| `NotFound` | 404: no such computer, template, state or task |
+| `EnvGone` | 410: the computer was destroyed (closed, or reaped by its lease); a subclass of `NotFound` |
+| `Conflict` | 409: the computer's state does not allow this operation |
+| `NotQuiescent` | 409: fork or save found no safe moment to capture; nothing was captured |
+| `CheckpointStale` | 409: the template's checkpoint predates this runtime; the installer must run again |
+| `Overloaded` | 429: the host is near its memory limit; nothing was started, try again later |
+| `DaemonUnavailable` | the server did not answer; after a POST, call `env.refresh()` |
+| `GuestError` | 502: the desktop's guest did not answer or refused the action |
+| `ActionFailed` | the action ran and exited non-zero (`returncode`, `output`, `error`) |
+| `EnvFailed` | a create, reset or fork child did not come up ready (`record`, `gates`, `cause`) |
+| `RestoreFailed`, `GateFailed`, `TaskSetupFailed` | subclasses of `EnvFailed`: restore failed, a gate failed (quarantined), the task's setup failed |
+| `ForkError` | some children failed (`ok`, `failed`, `state`) |
+| `BatchError` | some of `create_many` failed (`ok`, `failed`) |
+| `InvalidEpisode` | `verify()` on an invalid episode (`reward` attached); do not train on it |
+| `CheckerError` | the checker raised or could not run (`reward` attached) |
+
+Every gateway error reply carries a `request_id` (`gw_...`); include it when you report a problem. Full table with
+causes and fixes: [errors](https://console.drums.run/docs/reference/errors).
+
+## Configuration
+
+| Variable | Read by | Meaning |
+|---|---|---|
+| `DRUMS_URL` | SDK, `drums mcp` | the gateway or `drumsd` URL. Default `http://127.0.0.1:7070` |
+| `DRUMS_TOKEN` | SDK, `drums mcp` | the API key (`drums_sk_...`); sent as `Authorization: Bearer` |
+| `DRUMS_TOKEN_FILE` | `drums mcp` | a file holding the token, read when `DRUMS_TOKEN` is unset; then `/etc/drums/token` |
+| `DRUMS_ALLOW_INSECURE_HTTP` | SDK, `drums mcp` | `1` sends the token over plain HTTP to a host that is not loopback |
+| `DRUMSD_URL` | SDK | older name for `DRUMS_URL`, read when `DRUMS_URL` is unset |
+
+`drums.connect(url, token, timeout=900, retry_s=60, check=True, close_on_exit=True, handle_signals=True,
+allow_insecure_http=None)` takes the same values as arguments. In CI, store the key in the secret store and expose
+it only as `DRUMS_TOKEN` to the job that needs it ([API keys guide](https://console.drums.run/docs/guides/api-keys)).
## Development
```bash
git clone https://github.com/Drums-Labs/drums-python-sdk.git
cd drums-python-sdk
-python3 -m unittest discover -s tests -v # runs against a fake daemon; no network
+python3 -m unittest discover -s tests -v
+```
+
+The tests run against a fake gateway on `127.0.0.1` and need no account or network. CI runs them on Python 3.9,
+3.10, 3.11, 3.12 and 3.13 on every push and pull request, then builds the package and runs `twine check --strict`;
+the release workflow installs the built wheel into a clean venv on the same five versions and runs the suite against
+it. To do the same locally:
+
+```bash
+python3 -m pip install --upgrade build twine
+python3 -m build
+python3 -m twine check --strict dist/*
```
-See [CHANGELOG.md](CHANGELOG.md) for what changed in each version and [RELEASE.md](RELEASE.md) for how a release is cut.
+Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
+
+## Versioning and changelog
+
+Versions follow `MAJOR.MINOR.PATCH`. While the major version is 0, a minor release may change an interface and says
+so in [CHANGELOG.md](CHANGELOG.md), which lists every release with the runtime version it was built against. The
+package version is `drums.__version__`; `drums version` prints it. Releases are tagged `vX.Y.Z` and published to
+PyPI by the [release workflow](.github/workflows/release.yml) with Trusted Publishing; see [RELEASE.md](RELEASE.md).
+
+## Security
+
+Report a vulnerability privately through
+[GitHub's private reporting form](https://github.com/Drums-Labs/drums-python-sdk/security/advisories/new) or to
+security@drums.run, not in a public issue. [SECURITY.md](SECURITY.md) has the supported versions, the response time
+and the known limitations of the runtime the SDK talks to.
+
+## Contributing
+
+Bug reports and pull requests are welcome. [CONTRIBUTING.md](CONTRIBUTING.md) covers the setup, the tests, the
+sign-off and what a pull request needs. The project follows the [Contributor Covenant](CODE_OF_CONDUCT.md).
+
+## License
+
+[Apache License 2.0](LICENSE).
+
+## Status
+
+Beta. The `Client` and `Env` methods used in this README, the error classes and the environment variables are
+stable within 0.x: a change to any of them is listed in the changelog with a migration note. Stable: create, step,
+observe, screenshot, save, fork, reset, verify, close; the MCP tool list and its `confirm` rule; the transport
+rules. Not yet stable: `Client.runs`/`create_run` (the gateway's run endpoints are new), `HybridTools` (the browser
+tools need Chrome started with a DevTools port), and `Reward.trusted` on runtimes that send no audit (it is `None`
+there).
diff --git a/RELEASE.md b/RELEASE.md
index 5f2de49..2fa11a3 100644
--- a/RELEASE.md
+++ b/RELEASE.md
@@ -16,8 +16,9 @@ refuses to publish if the line is removed or `LICENSE` is a placeholder.
### 0.2 Register the Trusted Publisher on PyPI
-The `drums-sdk` project does not exist on PyPI yet, so register a **pending** publisher (it becomes the project's
-publisher on the first upload). Signed in to pypi.org as the account that will own the project:
+Done for `drums-sdk` since 0.2.5; kept here for a new project or a new owner account. Before the first upload,
+register a **pending** publisher (it becomes the project's publisher on that upload). Signed in to pypi.org as the
+account that owns the project:
1. Open https://pypi.org/manage/account/publishing/
2. Under "Add a new pending publisher", choose **GitHub** and enter exactly:
@@ -47,8 +48,7 @@ exists and OIDC otherwise. Never paste a token into a file, a command line or a
## 1. Merge the release PR
-Merge `pypi-release` into `main`. Confirm `main` is what you want
-to ship:
+Merge the release PR into `main`. Confirm `main` is what you want to ship:
```bash
git checkout main && git pull --ff-only
@@ -104,10 +104,9 @@ Then check https://pypi.org/project/drums-sdk/ and create the GitHub release fro
gh release create "v$V" --title "drums $V" --notes-file <(awk "/^## $V/{f=1;next} /^## /{f=0} f" CHANGELOG.md)
```
-## 5. After the first release
+## 5. Later releases
-- Later releases: bump `version` in `pyproject.toml` and `__version__` in `drums/__init__.py` together, add a
+- Bump `version` in `pyproject.toml` and `__version__` in `drums/__init__.py` together, add a
`CHANGELOG.md` entry, merge, then steps 2 to 4. The workflow fails if the tag and the version disagree.
- A version can be uploaded to PyPI exactly once. A broken release gets a new patch version, never a re-upload.
-- Update the install instructions in the docs (`console.drums.run/docs/quickstart` and
- `/docs/reference/python-sdk` still describe installing from a wheel file) to `pip install drums-sdk`.
+- When the docs mention a specific SDK version (quickstart, SDK reference, MCP guide), update them in the same week.
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..408e098
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,83 @@
+# Security policy
+
+## Supported versions
+
+| Version | Supported |
+|---|---|
+| 0.3.x | yes |
+| 0.2.x | security fixes only, until 0.4.0 is released |
+| earlier | no |
+
+The SDK uses only the Python standard library and has no runtime dependencies. Upgrade with `pip install -U drums-sdk`.
+
+## Reporting a vulnerability
+
+Report it privately, in this order of preference:
+
+1. GitHub's private reporting form:
+ [github.com/Drums-Labs/drums-python-sdk/security/advisories/new](https://github.com/Drums-Labs/drums-python-sdk/security/advisories/new).
+ It opens a private advisory that only the maintainers can see.
+2. Email: security@drums.run.
+
+Do not open a public issue, and do not include a live API key in the report (revoke it instead; see below).
+
+What to expect:
+
+- an acknowledgement within 3 business days;
+- an assessment and, where the report is confirmed, a fix or a mitigation within 30 days for the SDK itself. Problems
+ in the hosted service or the runtime the SDK talks to are passed to the people who run them the same day;
+- credit in the changelog if you want it.
+
+Please give us that time before publishing. If you do not hear back within the acknowledgement window, open an issue
+that says only "security report pending" and a maintainer will follow up privately.
+
+## If a key leaks
+
+An API key (`drums_sk_...`) is a bearer credential: whoever holds it acts as its owner, within the key's scopes.
+Revoke it at once under **API Keys** in [console.drums.run](https://console.drums.run) (revocation takes effect on
+the next request; valid keys are never cached), check the audit log for calls made with it, close any computers you
+do not recognise, and create a replacement. Rewriting git history does not undo a leak.
+
+## What this SDK guarantees
+
+- **Transport.** A token is sent over HTTPS, or over plain HTTP to loopback only (`localhost`, `127.0.0.0/8`,
+ `::1`). Any other `http://` URL raises `drums.InsecureTransport` before a request is made, unless the caller opts in
+ (`allow_insecure_http=True`, `DRUMS_ALLOW_INSECURE_HTTP=1`, `drums mcp --allow-insecure-http`).
+- **Redirects.** Followed only to the same origin (scheme, host, port), at most 5 hops, with the transport check on
+ every hop; anything else raises `drums.RedirectRefused` before it is followed. The token is never re-sent to another
+ host because a server said `Location`.
+- **No token in output.** The token is never printed, written or included in an error message by the SDK, the
+ `drums` command or the MCP server. `drums mcp --print-config` prints a placeholder.
+- **Destructive MCP tools need `confirm: true`.** `destroy_computer`, `delete_snapshot` and `revoke_api_key` are
+ refused before any request unless the arguments carry `confirm: true`. The caller supplies it; whether a person
+ approves the call is the MCP client's job. `reset` also discards desktop state and is not gated.
+- **Schema checks.** MCP tool arguments are checked against `drums/mcp_tools.json` before anything is sent.
+
+## Known limitations of the runtime the SDK talks to
+
+These describe Drums Cloud and `drumsd` as published at
+[Isolation and worker pools](https://console.drums.run/docs/concepts/isolation-and-worker-pools); they are not
+properties of this package, but anyone using it should know them.
+
+- **The isolation boundary between customers is the host.** A worker host is bound to one workspace; desktops of
+ different workspaces never share a host. Inside a host, desktops are separated by Linux namespaces (pid, mount,
+ network, ipc, uts, user), cgroups and a seccomp filter. That is process isolation within one trusted customer
+ boundary, not a virtual machine boundary: do not run desktops of parties that do not trust each other on one host.
+- **Desktops restored or forked from the same template share the template's uid range.** This is accepted only
+ inside a single trusted customer boundary. Per-desktop uid remapping is tracked as hardening required before any
+ untrusted multi-tenant use.
+- **Agents never escalate.** The desktop user is in no administrator group, every process it drives runs with
+ `no_new_privs`, and `sudo`, `su` and `pkexec` refuse. Task setup steps that need root are run by the runtime as
+ trusted provisioning; a task that needs the agent itself to act as root is refused with `drums.TaskUnsupported`.
+- **The hardened execution profile is the default on Drums Cloud.** A self-hosted `drumsd` runs with whatever
+ profile its operator installed; ask them which.
+- **Open item: a crashed application after a fork.** In daily-use tests of runtime 0.4.2, a forked desktop whose
+ browser had crashed could still return a reward marked valid. The reward audit (`Reward.trusted`, `audit_flags`)
+ and the alive-after-resume gate are the mitigations; until the fix is confirmed on the release you run against,
+ prefer `trusted` over `valid` for training signal and treat a score from a desktop whose application was not
+ running as suspect.
+- **No outbound network from a desktop.** Loopback only, no DNS. Anything a task needs from the network must be
+ provisioned by the operator.
+
+Rate limits, quotas and what the gateway checks on every call are in the
+[authentication reference](https://console.drums.run/docs/reference/authentication).
diff --git a/docs/assets/drums-symbol-light.svg b/docs/assets/drums-symbol-light.svg
new file mode 100644
index 0000000..8ef5bc4
--- /dev/null
+++ b/docs/assets/drums-symbol-light.svg
@@ -0,0 +1,7 @@
+
diff --git a/docs/assets/drums-symbol.svg b/docs/assets/drums-symbol.svg
new file mode 100644
index 0000000..40205b1
--- /dev/null
+++ b/docs/assets/drums-symbol.svg
@@ -0,0 +1,7 @@
+