Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
{
"name": "drums",
"description": "Isolated desktops for computer-use agents: start a computer from a template, act with GUI, shell and files, verify against a task checker, fork and reset, and read run results, all through the Drums MCP server.",
"version": "0.3.0",
"author": { "name": "Drums Labs" }
}
9 changes: 9 additions & 0 deletions .mcp.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
{
"mcpServers": {
"drums": {
"command": "drums",
"args": ["mcp"],
"env": { "DRUMS_URL": "${DRUMS_URL}", "DRUMS_TOKEN": "${DRUMS_TOKEN}" }
}
}
}
30 changes: 30 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,36 @@
All notable changes to the `drums` Python SDK. The SDK talks to drumsd over its HTTP API; the drumsd version each
SDK version was built against is noted where it matters.

## 0.3.0 - unreleased (after 0.2.5 is on PyPI)

The MCP server and the `drums` command. The hosted MCP endpoint on the gateway (`<gateway URL>/mcp`) is live already;
this release adds the local server and the client methods for the new gateway routes.

- `drums mcp` (the same as `python -m drums.mcp`): a stdio MCP server with the 34 workspace and desktop tools of
`drums/mcp_tools.json`, the list the gateway serves. `--env <computer id>` binds the desktop tools to one computer;
`--print-config claude|claude-local|cursor|codex` prints the matching client snippet with a placeholder key.
Destructive tools (`destroy_computer`, `delete_snapshot`, `revoke_api_key`) are refused unless the caller passes
`confirm: true` in the tool arguments, before any request is sent; the MCP client, not Drums, owns the user's
approval of such a call.
- Token transport rule, in the `Client` and the CLI: a token is sent over https, or over plain http to loopback
only (`localhost`, `127.0.0.0/8`, `::1`). Any other `http://` URL (`--url`, `DRUMS_URL`) raises the new
`drums.InsecureTransport` before any request (exit 2 with a one-line message from `drums mcp`); the message names
the host and the opt-ins, never the token. Opt in with `drums mcp --allow-insecure-http`,
`DRUMS_ALLOW_INSECURE_HTTP=1`, or `connect(..., allow_insecure_http=True)` / `Client(..., allow_insecure_http=True)`.
`drums.check_transport(url, token, allow_insecure_http=None)` is the check itself.
- Redirect rule: the `Client` follows a redirect only to the same origin (scheme, host, port) as the request, at
most `drums.MAX_REDIRECTS` (5) hops, and runs the transport check on every hop. A redirect to another origin
(another host or port, https to http) or a sixth hop raises the new `drums.RedirectRefused` before it is
followed, so the token is never re-sent elsewhere by way of a `Location` header (urllib's default follows and
re-sends `Authorization`). The message names the target's scheme, host and port only. `308` is followed like
`307` on every supported Python.
- `drums` console script (`drums mcp`, `drums version`); `mcp_tools.json` ships in the wheel.
- `Client.runs`, `create_run`, `run`, `api_keys`, `create_api_key`, `revoke_api_key`, `audit` for the gateway's
`/v1/runs`, `/v1/api-keys` and `/v1/audit` routes; `call()` takes extra headers.
- The repository is a Claude Code plugin (`.claude-plugin/plugin.json`, `.mcp.json`, the `drums-workflow` skill).
- `drums.hybrid` `write_file` sends chunks of 8000 base64 characters (the gateway caps a step argument at 8192);
`gui` code is at most 16384 characters.

## 0.2.5 - first release on PyPI

The first version published on PyPI, as `drums-sdk` (`pip install drums-sdk`; the import name stays `drums`). Versions 0.2.0 to 0.2.4 shipped as wheels sent with invites.
Expand Down
113 changes: 112 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,10 @@ export DRUMS_URL=https://beta.drums.run/gw # Drums Cloud gateway; or http://
export DRUMS_TOKEN=drums_sk_... # your API key
```

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.

Check the connection:

```python
Expand Down Expand Up @@ -82,7 +86,7 @@ for an invalid episode instead of returning a reward.
([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; `python -m drums.mcp` serves them to an agent over MCP (stdio).
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).
Expand All @@ -99,6 +103,113 @@ for an invalid episode instead of returning a reward.
- **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.

## MCP server

`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`.

```
drums mcp # all tools; desktop tools take computer_id
drums mcp --env <computer_id> # 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
```

The same tool list is served remotely by the gateway at `<GATEWAY_URL>/mcp` (MCP Streamable HTTP, authenticated
with a workspace API key; Drums MCP uses API keys, not OAuth). Replace `<GATEWAY_URL>` with your workspace's gateway
URL and `drums_sk_...` with a key from the console.

Claude Code, remote:

```
claude mcp add --transport http drums <GATEWAY_URL>/mcp --header "Authorization: Bearer drums_sk_..."
```

Claude Code, local (this package):

```
claude mcp add drums -e DRUMS_URL=<GATEWAY_URL> -e DRUMS_TOKEN=drums_sk_... -- drums mcp
```

Cursor (`~/.cursor/mcp.json` or `.cursor/mcp.json`):

```json
{"mcpServers": {"drums": {"url": "<GATEWAY_URL>/mcp", "headers": {"Authorization": "Bearer drums_sk_..."}}}}
```

Codex (`~/.codex/config.toml`):

```toml
[mcp_servers.drums]
command = "drums"
args = ["mcp"]
env = { DRUMS_URL = "<GATEWAY_URL>", 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.

### Tools

Workspace tools (the gateway's HTTP API; `*` needs the Drums gateway and answers "not available on this server"
against a plain drumsd):

| 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.<tool>` |

Desktop tools (each takes `computer_id`):

| tool | what it does |
|---|---|
| `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 (`<GATEWAY_URL>` 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.

## Development

```bash
Expand Down
Loading
Loading