From b81db0bd120524bfda631f5f9b4835dd5c4f1ad0 Mon Sep 17 00:00:00 2001 From: Sahil Jagtap Date: Fri, 13 Nov 2026 02:07:44 -0500 Subject: [PATCH 1/3] readme: launch layout with logo, badges, quickstart, computers, actions, verify, runs, MCP, async, errors, configuration, status Signed-off-by: Sahil Jagtap --- README.md | 487 ++++++++++++++++++++--------- docs/assets/drums-symbol-light.svg | 7 + docs/assets/drums-symbol.svg | 7 + 3 files changed, 349 insertions(+), 152 deletions(-) create mode 100644 docs/assets/drums-symbol-light.svg create mode 100644 docs/assets/drums-symbol.svg 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 + +

+ +

drums-python-sdk

+ +

+ Python SDK and MCP server for Drums: create, act on, fork, reset and verify isolated desktops for computer-use agents. +

+ +

+ PyPI version + Python versions + License + CI + Release + Docs +

+ +

+ Website · + Docs · + Benchmarks · + Console · + SDK reference · + Changelog +

+ +## 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/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 @@ + + + + + + + From 4e56d01c6f420c90d351a5280ff0348bcc6a61c0 Mon Sep 17 00:00:00 2001 From: Sahil Jagtap Date: Fri, 13 Nov 2026 02:07:44 -0500 Subject: [PATCH 2/3] repo: SECURITY.md, code of conduct, DCO sign-off in CONTRIBUTING, issue and PR templates, dependabot Signed-off-by: Sahil Jagtap --- .github/ISSUE_TEMPLATE/bug_report.yml | 60 +++++++++ .github/ISSUE_TEMPLATE/config.yml | 11 ++ .github/ISSUE_TEMPLATE/feature_request.yml | 36 ++++++ .github/PULL_REQUEST_TEMPLATE.md | 20 +++ .github/dependabot.yml | 16 +++ CODE_OF_CONDUCT.md | 135 +++++++++++++++++++++ CONTRIBUTING.md | 62 +++++++--- SECURITY.md | 83 +++++++++++++ 8 files changed, 409 insertions(+), 14 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/dependabot.yml create mode 100644 CODE_OF_CONDUCT.md create mode 100644 SECURITY.md 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/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/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). From 7441baf3e4a5403c728508164e43f09f44e59cd5 Mon Sep 17 00:00:00 2001 From: Sahil Jagtap Date: Fri, 13 Nov 2026 02:07:44 -0500 Subject: [PATCH 3/3] ci: test on 3.9 through 3.13 on every push; RELEASE.md drops the first-release wording Signed-off-by: Sahil Jagtap --- .github/workflows/ci.yml | 2 +- RELEASE.md | 15 +++++++-------- 2 files changed, 8 insertions(+), 9 deletions(-) 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/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.