Python SDK

Client.owned_envs

Client.owned_envs() -> list

Ids of the envs this client created and has not closed.

Returns

list[str] of computer ids this client created and has not closed.

Client.close

Client.close(timeout: float = 30.0) -> list

Close every env this client created and has not closed (in parallel). Envs that are already gone are skipped. Returns [(env_id, error or None)]. Saved states are not deleted here (their leases, or fork(keep_state=False), or client.delete_state, take care of them).

Returns

list[tuple[str, Exception | None]]

HTTP

DELETE /v1/slots/{id} for each owned computer

Client.call

Client.call(
    method: str,
    path: str,
    body=None,
    raw: bool = False,
    timeout: float | None = None,
    headers: dict | None = None,
)

One raw request. Every other method is built on it; use it for routes the SDK has no method for.

One request. GETs are retried while drumsd is unreachable (up to retry_s: a restarting drumsd comes back and reconciles); other methods are never retried, since their outcome is unknown after a dropped connection. headers are added to the request (e.g. Idempotency-Key). A redirect is followed only to the same origin (scheme, host, port), at most MAX_REDIRECTS hops; any other redirect raises RedirectRefused unfollowed.

Returns

Parsed JSON, or bytes with raw=True.

Raises

• A DrumsError subclass chosen by HTTP status and code (see Errors)
• RedirectRefused when the server redirects to another origin (scheme, host or port) or more than drums.MAX_REDIRECTS (5) times: the key is never re-sent elsewhere

Client.health

Client.health() -> dict

Returns

dict: version, launchable images, limits, lease defaults, capacity.

HTTP

GET /v1/health

Client.metrics

Client.metrics() -> dict

Aggregate metrics of the current window: op latency (create/reset/fork/step/verify/...), episodes by verdict, failures and retries by cause, rewards, and cost (host price x wall time, per valid episode / verified reward). The cost counts the whole window's wall time, idle time included: the window starts when drumsd started or at the last reset_metrics(), so call reset_metrics() at the start of a run to measure that run.

Returns

dict of the current window's metrics (measured compute cost, not billed).

HTTP

GET /v1/metrics

Client.reset_metrics

Client.reset_metrics() -> dict

Close the current metrics window (its ledger goes to drumsd's event log) and start a new one.

Returns

dict

HTTP

POST /v1/metrics/reset

Client.images

Client.images() -> list

What envs can be created from: installed images and saved states (API: GET /v1/checkpoints).

Returns

list[dict] of checkpoint records: base images and your saved states.

HTTP

GET /v1/checkpoints

Client.delete_state

Client.delete_state(state) -> dict

Delete a saved state (from save() or fork(); API: checkpoint): its template server stops and its images are freed. Refused (Conflict) while an env made from it still exists. drumsd also deletes a state by itself when its lease runs out (default: 30 min with no env made from it) or, for fork(keep_state=False), when its last env closes.

Returns

dict {id, deleted, freed_bytes}

Raises

• Conflict while a computer made from it exists
• NotFound

HTTP

DELETE /v1/checkpoints/{id}

Client.tasks

Client.tasks(domain: str | None = None) -> list

Returns

list[dict] of {id, domain, instruction, supported, unsupported_reason}.

HTTP

GET /v1/tasks

with drums.connect() as client:
    runnable = [t for t in client.tasks(domain="os") if t["supported"]]
    print(len(runnable), runnable[0]["id"])

Client.task

Client.task(task_id: str) -> dict

An OSWorld task JSON from the host's pinned checkout, by id or unique prefix (>= 8 characters).

Returns

dict: the OSWorld task JSON.

Raises

• NotFound

HTTP

GET /v1/tasks/{id}

Client.envs

Client.envs() -> list

The live envs on the host (drumsd >= 0.4 lists only those; older ones list every env, so destroyed ones are dropped here). These Env objects are not owned by this client: close_on_exit does not close them.

Returns

list[Env] of your live computers on this host (not owned by this client).

HTTP

GET /v1/slots

Client.env_records

Client.env_records(include_destroyed: bool = False, page_size: int = 500)

Every env record, live ones only or with the destroyed ones (their records are kept), as a generator over pages of page_size (GET /v1/slots?limit=&after=&include_destroyed=). An older drumsd answers with one list.

Returns

A generator of computer record dicts.

HTTP

GET /v1/slots?limit=&after=&include_destroyed=

Client.runs

Client.runs(kind: str | None = None, status: str | None = None, limit: int = 50) -> dict

The workspace's runs, newest first. Gateway only: a plain drumsd answers 404.

The workspace's runs, newest first (GET /v1/runs): {"items": [run rows], "next_cursor"}. kind filters (e.g. "evaluation"), status too (queued, running, completed, failed, cancelled).

Returns

dict: {items, next_cursor}

HTTP

GET /v1/runs

Client.create_run

Client.create_run(spec: dict, idempotency_key: str | None = None) -> dict

Queue a run from a RunSpec, the document the console's New run form submits. Needs runs:write.

Submit a RunSpec (POST /v1/runs): {"run_id", "operation_id", "status", "created"}. With idempotency_key (the Idempotency-Key header) the same key with the same spec returns the same run.

Returns

dict: {run_id, operation_id, status, created}

Raises

• DrumsError (403 quota_exceeded / budget_exceeded) when the execution or budget exceeds the workspace limits
• Conflict (409 wrong_state) when the Idempotency-Key was used with a different body

HTTP

POST /v1/runs

Client.run

Client.run(run_id: str) -> dict

One run (GET /v1/runs/{id}): its row, the attempts summary and the last events.

Returns

dict: the run, attempts and events

HTTP

GET /v1/runs/{id}

Client.api_keys

Client.api_keys() -> dict

Key metadata only; a key's secret is never returned after it was created.

The workspace's API keys, metadata only (GET /v1/api-keys): {"items": [{id, name, prefix, scopes, ...}]}.

Returns

dict: {items: [{id, name, prefix, scopes, ...}]}

HTTP

GET /v1/api-keys

Client.create_api_key

Client.create_api_key(
    name: str,
    scopes: list,
    expires_in_days: int | None = None,
) -> dict

Mint a key owned by this client's key owner. Owner and admin keys only; the scopes cannot exceed this client's own.

A new API key (POST /v1/api-keys): {"id", "prefix", "key", "expires_at"}. key is the plaintext, shown once; the scopes cannot exceed this client's own.

Returns

dict: {id, prefix, key, expires_at}; key is the whole key, shown once

Raises

• DrumsError (403 forbidden) from a member's key, or for a scope this client lacks

HTTP

POST /v1/api-keys

Client.revoke_api_key

Client.revoke_api_key(key_id: str) -> dict

Revoke a key now; it is refused on its next call. Owner and admin keys only; a key cannot revoke itself.

Revoke an API key (DELETE /v1/api-keys/{id}): {"id", "revoked_at"}. A key cannot revoke itself.

Returns

dict: {id, revoked_at, already}

HTTP

DELETE /v1/api-keys/{id}

Client.audit

Client.audit(
    action: str | None = None,
    limit: int = 50,
    cursor: str | None = None,
) -> dict

The workspace's audit log, newest first. Needs audit:read (owner and admin keys).

The workspace's audit log, newest first (GET /v1/audit): {"items": [events], "next_cursor"}. action filters by prefix (e.g. "mcp", "computer.create").

Returns

dict: {items, next_cursor}

HTTP

GET /v1/audit

Client.create

Client.create(
    image: str = 'osworld-ubuntu',
    task=None,
    *,
    from_state=None,
    setup: bool | None = None,
    idle_timeout: float | None = None,
    ttl: float | None = None,
) -> Env

A new env from an image (or from a saved state), with an optional OSWorld task whose setup runs now and after every reset. Raises RestoreFailed / GateFailed / TaskSetupFailed if it did not come up ready (the env still exists on the server, down or quarantined: close it, or let its lease reap it). idle_timeout / ttl (seconds): the env's lease. drumsd destroys it after idle_timeout s with no request naming it, or ttl s after it was created. None = the server's default (30 min idle, no TTL); 0 = no limit.

Returns

Env in state ready (owned by this client).

Raises

• RestoreFailed, GateFailed, TaskSetupFailed (subclasses of EnvFailed) if it did not come up ready; the computer exists on the server until closed
• TaskUnsupported (422) for a task that needs root
• Overloaded (429) when the host is full
• DrumsError with status 403 for quota_exceeded or budget_exceeded
• NotFound for an unknown image or saved state

HTTP

POST /v1/slots

with drums.connect() as client:
    with client.create(task="e0df059f", ttl=900) as env:
        env.wait_valid()
        print(env.id, env.state, env.episode)

Client.create_many

Client.create_many(
    n: int,
    image: str = 'osworld-ubuntu',
    task=None,
    *,
    from_state=None,
    workers: int = 8,
    idle_timeout: float | None = None,
    ttl: float | None = None,
) -> list

n envs created concurrently. All ready -> the list; otherwise BatchError(ok=[ready envs], failed=[(i, error)]).

Returns

list[Env] when all came up.

Raises

• BatchError(ok=[...], failed=[(i, error)]) if any failed: close ok yourself or let the client close them

HTTP

POST /v1/slots (n times)

Client.map

Client.map(fn, items, workers: int = 8) -> list

fn over items in threads; each result is the return value or the exception it raised (never dropped).

Returns

list: each result, or the exception it raised.

Env.last_forkproperty

Env.last_fork

Deprecated: use the ForkResult that fork() returns.

Deprecated (0.2.4): the last fork()'s raw server reply. Use the ForkResult fork() returns (.state, .checkpoint) or env.last_state.

Env.idproperty

Env.id

The computer's UUID (the id the console shows).

Env.episodeproperty

Env.episode

Episode number; increases with every reset.

Env.stateproperty

Env.state

ready, down, quarantined, destroyed, … as of the last record the client saw.

Env.validityproperty

Env.validity

{verdict: pending | valid | invalid, gates?} from the last record.

Env.taskproperty

Env.task

The task JSON the computer runs, or None.

Env.from_stateproperty

Env.from_state

The image or saved state this computer restores to on reset.

Env.refresh

Env.refresh() -> dict

Returns

dict: the current record (also stored as env.record).

HTTP

GET /v1/slots/{id}

Env.reset

Env.reset() -> Env

New episode from the image or saved state this env was made from (and the task's setup, for an env created with a task).

Returns

Env (self) with a new episode.

Raises

• Conflict on a quarantined computer
• EnvGone
• EnvFailed subclasses if the new episode did not come up

HTTP

POST /v1/slots/{id}/reset

Env.step

Env.step(action, screenshot: bool = False, check: bool = True) -> StepResult

pyautogui code (str) or an action dict: {"type": "pyautogui", "code"}, {"type": "execute", "command", "shell"}, {"type": "launch", "command", "shell"}, {"type": "sleep", "seconds"}. Screen 1920x1080, origin top left, pixels. pyautogui and execute run inside the env as its desktop user user (not root), with OSWorld's prefix (import pyautogui, time). See https://console.drums.run/docs/concepts/computers-and-templates#actions. check=True (default): an action that ran and exited non-zero raises ActionFailed with its exit status, output and error; check=False returns the result as is. A guest that does not answer or times out (120 s) raises GuestError either way.

Returns

StepResult

Raises

• ActionFailed (with check=True)
• GuestError (502) when the desktop does not answer
• Conflict on a quarantined computer
• EnvGone

HTTP

POST /v1/slots/{id}/step

r = env.step("pyautogui.click(960, 540)")
r = env.step({"type": "execute", "command": ["ls", "/home/user"]})
print(r.result["output"])

Env.observe

Env.observe() -> Observation

Returns

Observation: the PNG plus meta (episode, state, verdict, task id, instruction, steps, time).

HTTP

GET /v1/slots/{id}/screenshot, then GET /v1/slots/{id}

Env.screenshot

Env.screenshot() -> bytes

Returns

bytes: PNG, 1920 x 1080.

HTTP

GET /v1/slots/{id}/screenshot

Env.gates

Env.gates() -> dict

Returns

dict: the episode's gate report and verdict.

HTTP

GET /v1/slots/{id}/gates

Env.valid

Env.valid(timeout: float = 30.0) -> bool

Wait until the episode's verdict is no longer pending; True only when every gate passed.

Returns

bool

HTTP

GET /v1/slots/{id}/gates (polled)

Env.wait_valid

Env.wait_valid(timeout: float = 60.0) -> Env

Block until this episode's last gate (processes alive 5 s after resume) has resolved. Raises GateFailed if the episode is invalid. Act after this when your first actions may end processes: a process that exits in the first seconds after a restore cannot be told apart from a bad restore, so the episode would be flagged invalid.

Returns

Env (self)

Raises

• GateFailed if the episode is invalid
• DrumsError if still pending after timeout

HTTP

GET /v1/slots/{id}/gates (polled)

Env.verify

Env.verify(strict: bool = True) -> Reward

Run the task's checker on the current state. The server waits for the episode's last gate first. strict=True: raises InvalidEpisode (reward attached, flagged, with .invalid_reasons) if the episode is not valid, CheckerError if the checker failed. strict=False: returns the Reward; use .score only when .valid. On a quarantined env the checker is not run: score None, valid False, reason "quarantined: <why>". Note: OSWorld checkers may run a postconfig (save, close a window) that changes the desktop.

Returns

Reward

Raises

• InvalidEpisode (strict) when the episode is not valid; the reward is attached
• CheckerError (strict) when the checker failed

HTTP

POST /v1/slots/{id}/verify

reward = env.verify(strict=False)
if reward.valid:
    print("score", reward.score)
else:
    print("do not train on this:", reward.invalid_reasons)

Env.load_task

Env.load_task(task) -> Env

Load an OSWorld task into this ready env (setup runs now and after every reset).

Returns

Env (self)

HTTP

POST /v1/slots/{id}/task

Env.metrics

Env.metrics() -> dict

This env's metrics: op latency (reset/step/fork/verify/...), episodes by verdict, failures and retries by cause, rewards, lifetime, and its share of the host cost by env-seconds (API field: slot_seconds).

Returns

dict

HTTP

GET /v1/slots/{id}/metrics

Env.wait_quiescent

Env.wait_quiescent(timeout: float | None = None, window: float | None = None) -> dict

Block until this env's process tree is safe to capture: no process or thread starting or exiting for window seconds (server default 1 s), no task exiting, no unreaped zombie. fork() and save() already do this themselves, so calling it is optional (useful to time it, or to wait without capturing). Returns the wait record; raises NotQuiescent after timeout seconds (server default 30 s).

Returns

dict: the wait record.

Raises

• NotQuiescent

HTTP

POST /v1/slots/{id}/quiescent

Env.save

Env.save(
    name: str | None = None,
    quiesce_timeout: float | None = None,
    *,
    idle_timeout: float | None = None,
    ttl: float | None = None,
) -> State

Save the current state (API: capture; this env keeps running). client.create(from_state=...) starts from it. Safe right after an action: drumsd waits until the tree is quiescent and checks that the dump is that tree (NotQuiescent if it cannot within quiesce_timeout, server default 30 s; nothing is captured then). idle_timeout / ttl (seconds): the state's lease. drumsd deletes it after idle_timeout s with no env made from it (counted from its creation or its last env's close), or ttl s after it was made once no env uses it. None = the server's default (30 min idle, no TTL); 0 = no limit.

Returns

State: pass it as client.create(from_state=state).

Raises

• NotQuiescent
• DrumsError 403 quota_exceeded at the host's saved-state limit

HTTP

POST /v1/slots/{id}/capture

Env.prefork

Env.prefork(
    n: int,
    quiesce_timeout: float | None = None,
    *,
    keep_state: bool = True,
    idle_timeout: float | None = None,
    ttl: float | None = None,
    state_idle_timeout: float | None = None,
    state_ttl: float | None = None,
) -> dict

Prepare the next fork(n) in the background right after an action, so the fork is fast when you call it. Optional; fork() alone always works.

Prepare fork(n) now, in the background (API: prefork), and return at once. Call it right after an action; the next fork(n) with the same keep_state then gets these children if the env took no input since, no process started or exited in it, and its desktop state hash is unchanged (else it is discarded and the fork runs as usual). Any input (step, reset) discards it; so does a prefork nobody claims within the daemon's prefork_max_age_s (default 120 s). The children are the env as it was when it went quiet after the action.

Returns

dict (the runtime's acknowledgement); the children are handed out by the next fork(n), or discarded after any input or 120 s

HTTP

POST /v1/slots/{id}/prefork on a drumsd; the gateway does not serve this route in this version (404 `not_found`)

Env.fork

Env.fork(
    n: int,
    strict: bool = True,
    quiesce_timeout: float | None = None,
    *,
    keep_state: bool = True,
    idle_timeout: float | None = None,
    ttl: float | None = None,
    state_idle_timeout: float | None = None,
    state_ttl: float | None = None,
) -> ForkResult

Save this state and start n independent children from it, concurrently (API: branch); this env keeps running. Safe right after an action (no sleep needed): the capture waits for a quiescent tree, see save(). Returns a ForkResult: the ready children (a list, as before) with .state, the saved state the fork made (also env.last_state). keep_state=False: drumsd deletes that state as soon as its last env is closed, so a loop does not leak one state (~600 MB of RAM) per fork; keep_state=True (default): it stays until client.delete_state(state) or its lease. idle_timeout/ttl: the children's leases (see create); state_idle_timeout/state_ttl: the state's (see save). strict=True: if any child failed, raises ForkError(ok=[ready children], failed=[EnvFailed...], state).

Returns

ForkResult: a list of child Envs with .state, .checkpoint, .failed, .seconds.

Raises

• ForkError (strict)
• NotQuiescent
• Overloaded
• DrumsError 403 quota_exceeded

HTTP

POST /v1/slots/{id}/branch

with env.fork(2, keep_state=False) as kids:      # closes the children at the end
    rewards = client.map(lambda k: k.verify(strict=False), kids)

Env.branch

Env.branch(
    n: int,
    strict: bool = True,
    quiesce_timeout: float | None = None,
    *,
    keep_state: bool = True,
    idle_timeout: float | None = None,
    ttl: float | None = None,
    state_idle_timeout: float | None = None,
    state_ttl: float | None = None,
) -> ForkResult

Alias of fork (the 0.1 name).

Save this state and start n independent children from it, concurrently (API: branch); this env keeps running. Safe right after an action (no sleep needed): the capture waits for a quiescent tree, see save(). Returns a ForkResult: the ready children (a list, as before) with .state, the saved state the fork made (also env.last_state). keep_state=False: drumsd deletes that state as soon as its last env is closed, so a loop does not leak one state (~600 MB of RAM) per fork; keep_state=True (default): it stays until client.delete_state(state) or its lease. idle_timeout/ttl: the children's leases (see create); state_idle_timeout/state_ttl: the state's (see save). strict=True: if any child failed, raises ForkError(ok=[ready children], failed=[EnvFailed...], state).

Env.quarantine

Env.quarantine(reason: str = 'client') -> dict

Returns

dict: the record.

HTTP

POST /v1/slots/{id}/quarantine

Env.release

Env.release() -> dict

Kill a quarantined env's processes; it becomes down and a reset restores it.

Returns

dict: the record (down); call reset() next.

HTTP

POST /v1/slots/{id}/release

Env.close

Env.close() -> dict

Destroy this env (its records are kept on the host). A no-op on an env that is already gone (closed here or elsewhere, or reaped by its lease).

Returns

dict: the destroyed record.

HTTP

DELETE /v1/slots/{id}

Env.guest

Env.guest() -> GuestClient

An OSWorld guest-server-like transport (execute, launch, screenshot, screen_size, platform) over the API.

Returns

GuestClient

ForkResult.close

ForkResult.close() -> None

Close every child (already closed ones are skipped).

HTTP

DELETE /v1/slots/{id} for each child

ForkResult.delete_state

ForkResult.delete_state() -> dict | None

Close the children, then delete the saved state now (NotFound/EnvGone-safe).

Returns

dict | None

HTTP

DELETE /v1/checkpoints/{id}

StepResult.resultproperty

StepResult.result

The guest's reply: status, returncode, output, error.

StepResult.secondsproperty

StepResult.seconds

Seconds the step took inside the runtime.

StepResult.observationproperty

StepResult.observation

An Observation when the step asked for a screenshot.

GuestClient.execute

GuestClient.execute(command, shell: bool = False, allow_rc=(0,), timeout=None) -> dict

GuestClient.launch

GuestClient.launch(command, shell: bool = False) -> None

GuestClient.screenshot

GuestClient.screenshot() -> bytes

GuestClient.screen_size

GuestClient.screen_size()

GuestClient.platform

GuestClient.platform(timeout=10) -> str

AsyncClient.create

async AsyncClient.create(image: str = 'osworld-ubuntu', task=None, **kw) -> AsyncEnv

Returns

AsyncEnv

AsyncClient.health

async AsyncClient.health()

AsyncClient.metrics

async AsyncClient.metrics()

AsyncClient.task

async AsyncClient.task(task_id)

AsyncClient.delete_state

async AsyncClient.delete_state(state)

AsyncClient.close

async AsyncClient.close()

Close every env this client created and has not closed (see Client.close).

AsyncEnv.idproperty

AsyncEnv.id

AsyncEnv.episodeproperty

AsyncEnv.episode

AsyncEnv.step

async AsyncEnv.step(action, screenshot: bool = False)

AsyncEnv.observe

async AsyncEnv.observe()

AsyncEnv.reset

async AsyncEnv.reset()

AsyncEnv.verify

async AsyncEnv.verify(strict: bool = True)

AsyncEnv.fork

async AsyncEnv.fork(n: int, strict: bool = True, quiesce_timeout=None, **kw)

As Env.fork (keep_state=, idle_timeout=, ttl=, state_idle_timeout=, state_ttl=): a ForkResult of AsyncEnvs.

Returns

ForkResult of AsyncEnv

AsyncEnv.save

async AsyncEnv.save(name=None, quiesce_timeout=None, **kw)

AsyncEnv.wait_quiescent

async AsyncEnv.wait_quiescent(timeout=None, window=None)

AsyncEnv.metrics

async AsyncEnv.metrics()

AsyncEnv.close

async AsyncEnv.close()