HTTP API

Health

The runtime version, the images you can launch, per-desktop limits, lease defaults and the host's live capacity.

Python SDK: client.health()

• Needs a valid key but no scope.
• checkpoints lists only the base images of template versions your workspace may launch on this host; saved states are not listed here.
• capacity.live counts live desktops on the host; capacity.max is the host's desktop limit. The host serves one workspace.

curl -s "$DRUMS_URL/v1/health" -H "Authorization: Bearer $DRUMS_TOKEN"

{"ok":true,"version":"0.4.2","criu":{"sha256":"93403b4a…"},"image_sha256":"6bf667a8…",
 "checkpoints":[{"id":"osworld-ubuntu","stale_reason":null}],
 "limits":{"max_concurrent_restores":4,"memory_mib":4096,"swap_mib":0,"vcpus":4},
 "leases":{"defaults":{"env_idle_timeout_s":1800,"env_ttl_s":null,"reap_interval_s":15,"state_idle_timeout_s":1800,"state_ttl_s":null}},
 "capacity":{"live":0,"max":10}}

Host metrics

The runtime's aggregate metrics for the current window: operation latencies, episodes by verdict, failures by cause, lease reaps and measured compute cost.

Python SDK: client.metrics()

• The host serves one workspace, so these are your workspace's numbers. The gateway adds cost_label: "measured compute cost (not billed)".
• The window starts when the runtime started or at the last metrics reset, and its wall time includes idle time.

curl -s "$DRUMS_URL/v1/metrics" -H "Authorization: Bearer $DRUMS_TOKEN" | jq '{episodes: .usage.episodes, create: .usage.ops.create, cost_label}'

{"episodes":{"ended_pending":6,"invalid":0,"valid":17,"valid_fraction_of_judged":1},
 "create":{"failed":0,"mean_s":0.686,"n":23,"p50_s":0.507,"p95_s":1.679,"samples_kept":23,"seconds_total":15.782},
 "cost_label":"measured compute cost (not billed)"}

Reset host metrics

Closes the current metrics window (its ledger goes to the runtime's event log) and starts a new one. Call it at the start of a measurement to measure only that run.

Python SDK: client.reset_metrics()

• Recorded in the audit log as host.metrics_reset.
• Refused for run tokens (console runs).

curl -s -X POST "$DRUMS_URL/v1/metrics/reset" -H "Authorization: Bearer $DRUMS_TOKEN"

List tasks

Every OSWorld task in the host's pinned checkout: id, domain, instruction, and whether this host can run it.

Python SDK: client.tasks(domain=None)

• Needs computers:read or runs:read.
• domain filters by task domain: chrome, gimp, libreoffice_calc, libreoffice_impress, libreoffice_writer, multi_apps, os, thunderbird, vlc, vs_code.
• supported: false marks tasks that need the agent itself to act as root; creating a desktop with one is refused (422 task_unsupported).

curl -s "$DRUMS_URL/v1/tasks?domain=os" -H "Authorization: Bearer $DRUMS_TOKEN" | jq '.[0]'

{"domain":"os","id":"13584542-872b-42d8-b299-866967b5c3ef",
 "instruction":"I click in terminal: terminal->132x43 to change terminal size but after each reboot …",
 "supported":true,"unsupported_reason":null}

Get a task

One task's full OSWorld JSON (setup config, evaluator, instruction, …), by id or by a unique prefix of at least 8 characters.

Python SDK: client.task(task_id)

• Needs computers:read or runs:read.
• Pass the returned JSON as task when you create a desktop.

curl -s "$DRUMS_URL/v1/tasks/e0df059f" -H "Authorization: Bearer $DRUMS_TOKEN" | jq '{id, instruction, evaluator: .evaluator.func}'

{"id":"e0df059f-28a6-4169-924f-b9623e7184cc",
 "instruction":"I have a directory named \"todo_list_Jan_1\". Can you help me change its name into \"todo_list_Jan_2\"?",
 "evaluator":"exact_match"}

List images and saved states

What a desktop can be created from: the base images of your launchable template versions (by name, e.g. osworld-ubuntu) and your workspace's live saved states on this host (by snapshot UUID).

Python SDK: client.images()

• Saved states of other workspaces are never listed.
• captured_from is the computer id a saved state was taken from (null for base images).

curl -s "$DRUMS_URL/v1/checkpoints" -H "Authorization: Bearer $DRUMS_TOKEN" | jq '[.[] | {id, captured_from, stale}]'

[{"id":"osworld-ubuntu","captured_from":null,"stale":false}]

Get an image or saved state

One record from the list above, by base image name or snapshot UUID.

curl -s "$DRUMS_URL/v1/checkpoints/$SNAPSHOT_ID" -H "Authorization: Bearer $DRUMS_TOKEN" | jq '{id, captured_from, lease, stale}'

{"id":"ac6feaf8-275e-4c39-adbd-11b5fe518273","captured_from":"a5af0c19-efee-4c07-acaf-4e90a7d2dd58",
 "lease":{"idle_timeout_s":1800,"ttl_s":null},"stale":false}

Delete a saved state

Frees a saved state on the host (about 0.6 GB of host memory each). Base images cannot be deleted.

Python SDK: client.delete_state(state)

• Refused while a desktop made from the saved state still exists (409).
• The installed query parameter of drumsd is refused (403): installed images are managed by the operator.
• Recorded in the audit log as snapshot.delete.

curl -s -X DELETE "$DRUMS_URL/v1/checkpoints/$SNAPSHOT_ID" -H "Authorization: Bearer $DRUMS_TOKEN"

{"deleted":true,"freed_bytes":571428860,"id":"ac6feaf8-275e-4c39-adbd-11b5fe518273"}

List computers

Your workspace's computers on this host. With no query: a bare array of live computers. With any query parameter: a page {items, next_after}.

Python SDK: client.envs(), client.env_records()

• Ids are computer UUIDs (the same ids the console shows).
• include_destroyed=true adds closed computers (their records are kept). limit is 1..5000 (500 by default in the paged form); pass next_after as after for the next page.

curl -s "$DRUMS_URL/v1/slots?limit=10" -H "Authorization: Bearer $DRUMS_TOKEN" | jq '{ids: [.items[].id], next_after}'

{"ids":["a5af0c19-efee-4c07-acaf-4e90a7d2dd58"],"next_after":null}

Create a computer

Starts a desktop from a base image or one of your saved states, optionally with an OSWorld task whose setup runs now (and after every reset). Synchronous: the reply is the computer record once it is up.

Python SDK: client.create(image, task, from_state=, setup=, idle_timeout=, ttl=)

• Every computer gets a lifetime. ttl_s absent or <= 0 gives the workspace default (3600 s unless your owner changed it); larger values are capped at the workspace maximum (14400 s by default); the minimum is 60 s.
• idle_timeout_s defaults to 1800 s and is never longer than the lifetime.
• Check state in the reply: ready is up; a reply in down or quarantined means the restore or a gate failed (the SDK raises RestoreFailed/GateFailed). validity.verdict starts pending and resolves about 5 s after ready.
• Recorded in the audit log as computer.create; the computer appears in the console under Computers.

curl -s "$DRUMS_URL/v1/tasks/e0df059f" -H "Authorization: Bearer $DRUMS_TOKEN" \
  | jq '{checkpoint: "osworld-ubuntu", task: ., ttl_s: 900}' \
  | curl -s -X POST "$DRUMS_URL/v1/slots" -H "Authorization: Bearer $DRUMS_TOKEN" -H "Content-Type: application/json" -d @- \
  | jq '{id, state, episode, validity, lease}'

{"id":"a5af0c19-efee-4c07-acaf-4e90a7d2dd58","state":"ready","episode":1,
 "validity":{"gates":["alive_after_resume"],"verdict":"pending"},
 "lease":{"idle_timeout_s":900,"ttl_s":900}}

Get a computer

The computer's current record: state, episode, gate report, validity, lease and task.

Python SDK: env.refresh()

• A closed computer still answers 200 with state: "destroyed".
• Counts as a use of the computer (resets its idle clock).

curl -s "$DRUMS_URL/v1/slots/$COMPUTER_ID" -H "Authorization: Bearer $DRUMS_TOKEN" | jq '{id, state, episode, verdict: .validity.verdict, lease_expires_epoch}'

{"id":"26ce04d4-50c1-478e-a771-dbe57bb93eb1","state":"ready","episode":1,"verdict":"pending","lease_expires_epoch":1793816168.91}

Close a computer

Destroys the desktop. Idempotent: closing a closed computer returns its destroyed record again.

Python SDK: env.close()

• Recorded in the audit log as computer.delete. Measured cost stops.
• Saved states made from it are not deleted.

curl -s -X DELETE "$DRUMS_URL/v1/slots/$COMPUTER_ID" -H "Authorization: Bearer $DRUMS_TOKEN" | jq '{id, state, closed_epoch}'

{"id":"a5af0c19-efee-4c07-acaf-4e90a7d2dd58","state":"destroyed","closed_epoch":1793813681.21}

Act

Runs one action in the desktop: pyautogui code, a command (execute), a background command (launch) or a sleep. Returns the guest's result and the episode's validity at that moment.

Python SDK: env.step(action, screenshot=False, check=True)

• Actions run inside the desktop as the unprivileged user user (uid 1000) with no network. The screen is 1920 x 1080, origin top left.
• A non-zero result.returncode is still HTTP 200; the SDK raises ActionFailed for it unless check=False.
• screenshot: true adds screenshot_png_b64 to the reply.

curl -s -X POST "$DRUMS_URL/v1/slots/$COMPUTER_ID/step" -H "Authorization: Bearer $DRUMS_TOKEN" -H "Content-Type: application/json" \
  -d '{"action": {"type": "pyautogui", "code": "pyautogui.moveTo(960, 540)"}}'

{"episode":1,"result":{"error":"","output":"","returncode":0,"status":"success"},
 "screenshot_png_b64":null,"seconds":0.187,"validity":{"verdict":"valid"}}

Screenshot

The current screen as a PNG (1920 x 1080, 8-bit RGB, about 1.7 MB).

Python SDK: env.screenshot(), env.observe()

• Content-Type: image/png.

curl -s "$DRUMS_URL/v1/slots/$COMPUTER_ID/screenshot" -H "Authorization: Bearer $DRUMS_TOKEN" -o screen.png && file screen.png

screen.png: PNG image data, 1920 x 1080, 8-bit/color RGB, non-interlaced

Gate report

The current episode's gate report and verdict (pending, valid or invalid).

Python SDK: env.gates(), env.valid(), env.wait_valid()

• The verdict is pending for about 5 s after create, reset or fork (the alive_after_resume gate).

curl -s "$DRUMS_URL/v1/slots/$COMPUTER_ID/gates" -H "Authorization: Bearer $DRUMS_TOKEN" | jq '{verdict: .validity.verdict, gates: [.gates.gates[] | "\(.gate)=\(.status)"]}'

{"verdict":"valid","gates":["lock_applied=pass","lock_pre_resume=pass","init_identity=pass","cgroup=pass","mount_table=pass",
 "netns=pass","guest_ready=pass","state_hash=pass","isolation=pass","alive_after_resume=pass"]}

Verify

Runs the task's checker on the current desktop and returns the score together with the episode's validity. The runtime waits for the episode's last gate first.

Python SDK: env.verify(strict=True)

• Use score only when valid is true. On a quarantined computer the checker does not run: score is null and checker_skipped says why.
• Some OSWorld checkers run a postconfig step (save a file, close a window) that changes the desktop.

Body: none, or an empty JSON object {}.

curl -s -X POST "$DRUMS_URL/v1/slots/$COMPUTER_ID/verify" -H "Authorization: Bearer $DRUMS_TOKEN" -H "Content-Type: application/json" -d '{}' \
  | jq '{score, valid, invalid_reasons, checker: .checker.func, seconds}'

{"score":0,"valid":true,"invalid_reasons":[],"checker":"exact_match","seconds":0.09}

Reset

Starts a new episode from the image or saved state the computer was made from (and reruns the task's setup). The episode number increases; gates run again.

Python SDK: env.reset()

• No body.
• Recorded in the audit log as computer.restart.

curl -s -X POST "$DRUMS_URL/v1/slots/$COMPUTER_ID/reset" -H "Authorization: Bearer $DRUMS_TOKEN" | jq '{state, episode, verdict: .validity.verdict}'

{"state":"ready","episode":2,"verdict":"pending"}

Load a task

Loads an OSWorld task into a ready computer: its setup runs now and after every reset.

Python SDK: env.load_task(task)

• Recorded in the audit log as computer.task.

curl -s "$DRUMS_URL/v1/tasks/e0df059f" -H "Authorization: Bearer $DRUMS_TOKEN" | jq '{task: .}' \
  | curl -s -X POST "$DRUMS_URL/v1/slots/$COMPUTER_ID/task" -H "Authorization: Bearer $DRUMS_TOKEN" -H "Content-Type: application/json" -d @- \
  | jq '{state, task: .task.id}'

{"state":"ready","task":"e0df059f-28a6-4169-924f-b9623e7184cc"}

Computer metrics

This computer's operation latencies, episodes by verdict, failures and retries, lifetime, and its share of the host's measured compute cost by desktop-seconds.

Python SDK: env.metrics()

• Cost fields are measured compute cost, not a bill.

curl -s "$DRUMS_URL/v1/slots/$COMPUTER_ID/metrics" -H "Authorization: Bearer $DRUMS_TOKEN" | jq '{state, lifetime_s, episodes: .usage.episodes}'

{"state":"ready","lifetime_s":12.103,"episodes":{"ended_pending":0,"invalid":0,"valid":1,"valid_fraction_of_judged":1}}

Save state

Saves the computer's current state (memory and disk) as a saved state on the host; the computer keeps running. Create computers from it with checkpoint: <id>.

Python SDK: env.save(name=None, quiesce_timeout=None, idle_timeout=, ttl=)

• The runtime first waits until the process tree is quiet (no process or thread starting or exiting for 1 s), so it is safe right after an action.
• The reply's id is a snapshot UUID; the console lists it under Snapshots. id in the body is kept as the snapshot's display name only.
• Saved states live in host memory: they are lost if the host reboots. The host holds a limited number (quota_exceeded with details.limit: max_saved_states).
• Recorded in the audit log as computer.snapshot.

curl -s -X POST "$DRUMS_URL/v1/slots/$COMPUTER_ID/capture" -H "Authorization: Bearer $DRUMS_TOKEN" -H "Content-Type: application/json" -d '{"id": "after-setup"}' \
  | jq '{id, captured_from, expected_state_hash, seconds: .quiescence.seconds}'

{"id":"ac6feaf8-275e-4c39-adbd-11b5fe518273","captured_from":"a5af0c19-efee-4c07-acaf-4e90a7d2dd58",
 "expected_state_hash":"44f4a841…","seconds":2.185}

Fork

Saves the computer's state and starts n independent computers from it, concurrently; the parent keeps running. Each child starts a new episode with its own gate report.

Python SDK: env.fork(n, strict=True, quiesce_timeout=None, keep_state=True, idle_timeout=, ttl=, state_idle_timeout=, state_ttl=)

• n is 1..64 in the body and at most the host's max_fork_n; the children count against your live-computer limit.
• Children get lifetimes like a create (ttl_s clamped to the workspace default and maximum).
• delete_state_with_children: true deletes the fork's saved state when its last child closes (the SDK's keep_state=False). Otherwise the saved state stays until you delete it or its lease runs out.
• A child that did not start is returned as {error} in children.
• Recorded in the audit log as computer.fork.

curl -s -X POST "$DRUMS_URL/v1/slots/$COMPUTER_ID/branch" -H "Authorization: Bearer $DRUMS_TOKEN" -H "Content-Type: application/json" \
  -d '{"n": 2, "delete_state_with_children": true, "ttl_s": 600}' \
  | jq '{state, seconds, children: [.children[] | {id, state, verdict: .validity.verdict}]}'

{"state":"3b71ae6d-9228-44e8-a870-bdfb1c688501","seconds":2.674,
 "children":[{"id":"626baf25-afa2-4519-8d63-15eb1abfc8ac","state":"ready","verdict":"pending"},
             {"id":"104cf8d3-d161-4101-89f6-b04149978fd8","state":"ready","verdict":"pending"}]}

Wait until quiet

Blocks until the computer's process tree is safe to capture, without capturing. Save and fork already do this; use it to time the wait.

Python SDK: env.wait_quiescent(timeout=None, window=None)

curl -s -X POST "$DRUMS_URL/v1/slots/$COMPUTER_ID/quiescent" -H "Authorization: Bearer $DRUMS_TOKEN" -H "Content-Type: application/json" -d '{}' | jq '{quiescent, waited_s, processes}'

{"quiescent":true,"waited_s":1.013,"processes":53}

Quarantine

Marks the computer's state as untrusted: the episode becomes invalid and steps, resets and saves are refused. Use it when your harness detects a broken episode.

Python SDK: env.quarantine(reason="client")

• Recorded in the audit log as computer.quarantine.

curl -s -X POST "$DRUMS_URL/v1/slots/$COMPUTER_ID/quarantine" -H "Authorization: Bearer $DRUMS_TOKEN" -H "Content-Type: application/json" -d '{"reason": "harness check failed"}' \
  | jq '{state, reason, validity}'

{"state":"quarantined","reason":"harness check failed","validity":{"gates":["not_quarantined"],"verdict":"invalid"}}

Release

Kills a quarantined computer's processes; it becomes down, and a reset restores it with a new, judged episode.

Python SDK: env.release()

• Recorded in the audit log as computer.release.

Body: none, or an empty JSON object {}.

curl -s -X POST "$DRUMS_URL/v1/slots/$COMPUTER_ID/release" -H "Authorization: Bearer $DRUMS_TOKEN" -H "Content-Type: application/json" -d '{}' | jq '{state, reason}'

{"state":"down","reason":"released from quarantine: harness check failed"}

List runs

The workspace's runs (evaluations and scripted tests), newest first. Scope runs:read.

• Query: kind (evaluation or scripted_test), status (a run status), limit (1 to 200, default 50), cursor (the next_cursor of the previous page).
• Each item is the run record without the runner lease (leased_by, lease_until).
• This route exists only on the gateway; a plain drumsd answers 404.

curl -s "$DRUMS_URL/v1/runs?kind=evaluation&limit=2" -H "Authorization: Bearer $DRUMS_TOKEN" | jq '{n: (.items | length), next_cursor}'

Submit a run

Queues a run from a RunSpec, the same document the console's New run form submits. The host's runner picks it up. Scope runs:write.

• The body is the RunSpec: name, kind (evaluation or scripted_test), task_set_id, task_ids, template_version_id, agent ({kind: scripted} or {kind: model, endpoint_url, model, secret_ref_id}), execution (parallelism, fork_n, prefix_steps, max_steps, rounds), budget (usd, max_duration_s).
• Checked before anything is queued: the task set and template version are visible to the workspace, every task is in the set and supported, a scripted agent names tasks with a recipe, a model agent's endpoint host is allowed by its secret reference, the execution fits the workspace limits, and the budget fits the remaining spend of the period. The first problem is the error message; every problem is in details.issues.
• Idempotency-Key header: the same key with the same body returns the same run (created: false, 200). Without the header every call is a new run.
• Recorded in the audit log as run.create.

jq -n --arg task_set "$TASK_SET_ID" --arg template_version "$TEMPLATE_VERSION_ID" '{
  name: "smoke-1", kind: "scripted_test",
  task_set_id: $task_set, task_ids: ["e0df059f-28a6-4169-924f-b9623e7184cc"],
  template_version_id: $template_version, agent: {kind: "scripted"},
  execution: {parallelism: 1, fork_n: 1, prefix_steps: 5, max_steps: 3, rounds: 1},
  budget: {usd: 1, max_duration_s: 600}}' \
  | curl -s -X POST "$DRUMS_URL/v1/runs" -H "Authorization: Bearer $DRUMS_TOKEN" -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" -d @-

Get a run

One run with an attempts summary and its last 20 events. Scope runs:read.

• The run record without the runner lease, plus attempts: {total, done, succeeded, verified_valid} and events (newest first: seq, type, event_at, attempt_id, payload).
• A run of another workspace is 404, never 403.

curl -s "$DRUMS_URL/v1/runs/$RUN_ID" -H "Authorization: Bearer $DRUMS_TOKEN" | jq '{status, stop_reason, attempts, events: (.events | length)}'

List API keys

Metadata of the workspace's keys: id, name, prefix, scopes, owner, expiry, last use, revocation. Never a secret. Any key.

• The prefix is the 12 characters after drums_sk_; the key itself is stored only as a hash and cannot be shown again.

curl -s "$DRUMS_URL/v1/api-keys" -H "Authorization: Bearer $DRUMS_TOKEN" | jq '.items[] | {name, prefix, scopes, revoked_at}'

Create an API key

Mints a key owned by the calling key's owner. The plaintext key is in this reply once and nowhere else.

• key in the reply is the whole key (prefix and 43-character secret), shown once; the example shortens it.
• Only an owner or admin key may create keys (403 otherwise).
• The new key's scopes cannot exceed the calling key's effective scopes (its scopes intersected with its owner's role); the refused scopes are listed in details.scopes.
• Recorded in the audit log as api_key.create (name, prefix and scopes; never the key).

curl -s -X POST "$DRUMS_URL/v1/api-keys" -H "Authorization: Bearer $DRUMS_TOKEN" -H "Content-Type: application/json" -d '{"name": "ci", "scopes": ["computers:read", "runs:read"], "expires_in_days": 30}'

Revoke an API key

Revokes a key now; it is refused on its next call. Idempotent.

• Only an owner or admin key may revoke keys (403 otherwise).
• A key cannot revoke itself (400): use another owner or admin key, or the console.
• A second call for an already revoked key returns its original revoked_at with already: true.
• Recorded in the audit log as api_key.revoke.

curl -s -X DELETE "$DRUMS_URL/v1/api-keys/$KEY_ID" -H "Authorization: Bearer $DRUMS_TOKEN"

Read the audit log

The workspace's audit events, newest first: who did what, when, with what outcome. Scope audit:read (owner and admin keys only; the role filter drops it from a member's key).

• Query: action (an exact action such as computer.create, or a prefix such as mcp, which matches every mcp.<tool> row), limit (1 to 200, default 50), cursor (the next_cursor of the previous page; it is the id of the last row).
• Rows: id, actor_kind (user, api_key, operator, system, mcp), actor_user_id, actor_api_key_id, action, target_type, target_id, outcome, error_code, request_id, origin, source_ip_redacted, metadata, created_at. Metadata never holds secrets, screenshots or file contents.

curl -s "$DRUMS_URL/v1/audit?action=computer&limit=2" -H "Authorization: Bearer $DRUMS_TOKEN" | jq '.items[] | {action, actor_kind, outcome, created_at}'