divergent/docs
Sandboxes · Reference

Sandbox MCP tools

Reference for the sandbox tools in the Divergent MCP server, with each tool's parameters and response.

The Divergent MCP server provides the sandbox operations of div sandbox and div agent as tools. Setup is on that page. The API key needs the sandboxes:read and sandboxes:write scopes. A key from div login has both.

Every sandbox parameter takes a sandbox’s name or id. Responses are JSON unless noted.

Tools

Tool Description
sandbox_create Create a sandbox and start it.
sandbox_list List the org’s sandboxes.
sandbox_update Change a sandbox’s idle timeout, whether it stops when its agents finish, or its metadata.
sandbox_stop Stop a sandbox, keeping its files and processes.
sandbox_resume Resume a stopped sandbox.
sandbox_fork Create a new sandbox with a copy of another’s files.
sandbox_destroy Delete a sandbox permanently.
sandbox_exec Run a command and return its exit code and output.
sandbox_read_file Read one file.
sandbox_write_file Write one file.
sandbox_desktop Start, stop or check the desktop.
sandbox_open_url Open URLs in the desktop’s browser.
sandbox_screenshot Return the screen, or part of it, as a PNG image.
sandbox_input Send one click, keystroke, drag or scroll, or read the pointer position.
sandbox_accessibility_tree Return what is on screen as a tree of nodes.
sandbox_accessibility_action Act on a node of the accessibility tree.
sandbox_create_token Create a token that opens only one sandbox’s desktop and screen.
agent_prompt Send a task to a coding agent in a sandbox.
agent_conversations List a sandbox’s conversations, or read one’s events.

A typical session:

  1. sandbox_create with idle_timeout_seconds, so a forgotten sandbox stops.
  2. sandbox_write_file and sandbox_exec, as many times as the task needs.
  3. sandbox_stop to pause, or sandbox_destroy when the work is finished.

Sandboxes

sandbox_create

Creates a sandbox and starts it. Returns the sandbox.

Parameter Type Description Default
name string Lower case letters, digits and dashes. sb- and six hex digits
size small, standard, large, xl See sizes and prices. small
secrets string[] Names of secrets to set as environment variables, read from environment. Each must include sandboxes in its products. The sandbox receives no others. []
environment string The secrets environment that secrets are read from. sandbox_resume reads from it again, and sandbox_fork keeps it. default
idle_timeout_seconds integer Stop after this many seconds without use. 0 or 60 to 604800 (7 days). 0 (never)
stop_when_agents_finish boolean Stop once the sandbox’s coding agents have finished a turn, no turn is running or queued, and nothing has used the sandbox for 2 minutes. false
metadata object Labels of your own, such as {"user": "42"}. Up to 16 keys of 1 to 40 lowercase letters, digits, _, . or -. Values are strings of up to 256 characters. {}
idempotency_key string A retry with the same key returns the same sandbox. none

The returned sandbox includes id, name, status, size, cpu, memory_gib, disk_gib, cents_per_hour, idle_timeout_seconds, stop_when_agents_finish, secrets (names only), environment, metadata, cost_cents and timestamps. A stopped sandbox’s stopped_reason is requested, idle, agents_finished or limit_reached.

A sandbox created with secrets, in any environment, cannot have a token. See sandbox_create_token.

create fails with unknown_environment when environment does not exist, and with unknown_secrets when a named secret is not in it or does not include sandboxes. Create the environment with create_environment, and set the secret with set_secret or set_secret_products. See Secret tools.

sandbox_list

Lists the org’s sandboxes, newest first, with status, size, hourly price, spend and metadata.

Parameter Type Description Default
all boolean Include deleted sandboxes. false
metadata object List only sandboxes that have every one of these keys with these values, such as {"user": "42"}. none

sandbox_update

Changes the idle timeout of a running or stopped sandbox, whether it stops when its agents finish, or its metadata. Pass at least one of the three. On a running sandbox, the timeout counts from now. Returns the sandbox.

Parameter Type Description Default
sandbox string Required.
idle_timeout_seconds integer 0 (never) or 60 to 604800. unchanged
stop_when_agents_finish boolean As in sandbox_create. unchanged
metadata object Replaces all existing metadata. {} removes it. Limits as in sandbox_create. unchanged

Use counts as: a command, a file read or write, an open SSH session, or a coding agent’s running turn. A process running in the sandbox does not count.

sandbox_stop

Stops a sandbox. Files and running processes are kept. A stopped sandbox is billed 6¢ per GiB a month for its stored data. Stopping a stopped sandbox succeeds. Returns the sandbox.

Parameter Type Description
sandbox string Required.

sandbox_resume

Resumes a stopped sandbox with its files and processes as they were. Returns the sandbox.

Parameter Type Description
sandbox string Required.

sandbox_fork

Creates a new running sandbox with a copy of another sandbox’s files, including uncommitted work. The source can be running or stopped. The new sandbox has its own bill. Running processes are not copied. Returns the new sandbox.

Parameter Type Description Default
sandbox string Required. The source.
name string Name of the new sandbox. sb- and six hex digits

sandbox_destroy

Deletes a sandbox and its stored data. Billing stops. This cannot be undone. Returns the sandbox.

Parameter Type Description
sandbox string Required.

Commands and files

sandbox_exec

Runs a command with sh -c in a running sandbox, as root, and returns when it finishes.

Parameter Type Description Default
sandbox string Required.
command string Required. A shell command line.
cwd string Working directory. /root
env object Environment variables for this command. {}
timeout_seconds integer 1 to 600. 60

Returns exit_code, stdout, stderr and truncated. Each stream is cut at 1 MB, and truncated is true when that happens. Values of the sandbox’s secrets are masked.

A command that exits non-zero is a normal response with its exit_code, not a tool error.

sandbox_read_file

Reads one file, up to 64 MB.

Parameter Type Description
sandbox string Required.
path string Required. Absolute, for example /root/out.json.

Returns path, encoding and content. encoding is utf-8 when the file is valid UTF-8 text, and base64 otherwise.

sandbox_write_file

Writes one file, up to 64 MB. Creates missing directories and replaces an existing file. Pass exactly one of content and content_base64.

Parameter Type Description
sandbox string Required.
path string Required. Absolute, for example /root/app.py.
content string Text to write.
content_base64 string Bytes to write, base64-encoded.

Returns path and size_bytes.

Desktop

The desktop is off until sandbox_desktop starts it. Every other desktop tool fails with no_desktop when it is not running. A sandbox created before an action existed refuses that action with desktop_outdated; create a new sandbox to use it. See Use the desktop and browser.

sandbox_desktop

Starts, stops or checks the desktop with Chromium. Starting takes a few seconds and costs nothing beyond the sandbox. Each open page uses 250 to 350 MB of memory.

Parameter Type Description Default
sandbox string Required.
action start, stop, status start
resolution string Screen size for start, for example 1920x1080. 1280x800

Returns running. While the desktop runs, it also returns size, display, vnc_port, devtools, browser, and watch: a dashboard link where a person can watch the screen live and take control.

Chromium’s DevTools protocol is at http://127.0.0.1:9222 inside the sandbox. Programs started with sandbox_exec while the desktop runs open on the screen.

sandbox_open_url

Opens each URL as a tab in the desktop’s Chromium.

Parameter Type Description
sandbox string Required.
urls string[] Required. At least one.

Returns {"done": "open"}.

sandbox_screenshot

Captures the screen, or part of it.

Parameter Type Description Default
sandbox string Required.
region integer[] [x0, y0, x1, y1]: the top-left and bottom-right corners of the part to capture, in screen pixels. The image is that part scaled up to fit the screen size, keeping its aspect ratio. the whole screen

Returns a PNG image and a text item with width and height. Without region, positions for sandbox_input are pixels in this image, from the top left. With region, they are not: convert them back to screen pixels.

sandbox_input

Sends one input to the desktop.

Parameter Type Used by Description
sandbox string all Required.
action click, move, down, up, drag, type, key, hold, scroll, cursor all Required.
x, y integer click, move, drag, scroll Position in screen pixels. Required for move and drag. Optional for click and scroll; give both or neither.
to_x, to_y integer drag Required. Where the drag ends.
text string type Required. Text to type.
keys string[] key, hold Required. Each a key or combination, for example "Return" or "ctrl+l".
button left, middle, right click Default left.
count integer click 1, 2 (double-click) or 3 (triple-click). Default 1.
double boolean click The same as count 2. Do not combine with count.
modifiers string click, drag, scroll Keys held down during the action: shift, ctrl, alt or super, joined by +, for example ctrl+shift.
direction up, down, left, right scroll Required.
amount integer scroll Notches, 1 to 100. Default 3.
repeat integer key Press the keys this many times, 1 to 100. Default 1.
seconds number hold Required. How long to hold the keys, 0 to 300. Decimals are allowed.
Action Effect
click Click at x, y, or where the pointer is when neither is given.
move Move the pointer.
down, up Press or release the left button where the pointer is.
drag Drag with the left button from x, y to to_x, to_y.
type Type the text where the keyboard focus is.
key Press each key or combination in turn.
hold Hold the keys down together for seconds.
scroll Scroll by wheel notches, at x, y when given.
cursor Return the pointer’s position.

Returns done with the action, or x and y for cursor. A parameter given to an action that does not use it is refused. Prefer sandbox_accessibility_action when the tree contains the control.

sandbox_accessibility_tree

Returns what is on screen as a tree of applications and their nodes.

Parameter Type Description Default
sandbox string Required.
app string Only this application, for example chromium. all
depth integer Maximum depth, 1 to 200. 60
include_hidden boolean Include nodes that are not on screen. false

Returns apps, nodes and truncated. Each node has ref, role, name, states, bounds ([x, y, width, height] in screenshot pixels), actions, and text for fields. Nodes with no name, text or action are left out, and their children take their place. truncated is true when the tree passed 4,000 nodes; narrow it with app or depth. The format is shown in div sandbox a11y.

The accessibility tree usually needs fewer steps and tokens than screenshots.

sandbox_accessibility_action

Acts on one node by its ref.

Parameter Type Description
sandbox string Required.
ref string Required. A ref from sandbox_accessibility_tree, for example n42.
action string Required. press, focus, set-text, read, or any name in the node’s actions.
text string Required for set-text. The field’s new text.
Action Effect
press Press a button or follow a link.
focus Move keyboard focus to the node.
set-text Replace the field’s text with text.
read Return the node’s current state.

Returns ref and done, or the node for read. Refs are valid until the tree is read again. If the node has changed since, the action is refused. Call sandbox_accessibility_tree again and retry.

sandbox_create_token

Creates a token that opens one sandbox’s desktop tools and live screen, and nothing else. Give it to a page or a program that must not hold your API key. The same as div sandbox token.

Parameter Type Description Default
sandbox string Required. The sandbox must have no secrets.
abilities ["view"], ["control"] view watches the screen and takes screenshots. control also sends input and starts or stops the desktop. ["control"]
expires_in_seconds integer How long the token works, 60 to 3600. 900
origins string[] Up to 10 pages that may use the token in a browser, each a scheme and host with no path: https://app.example.com. none

Returns token, sandbox, abilities, origins and expires_at. The token is shown once.

  • A token reaches only a sandbox that names no secrets, and only its desktop. It does not reach commands, files, SSH, coding agents, stop or destroy.
  • Without origins, a request from a browser is refused. Requests from a server, which send no Origin header, work on every plan.
  • The token stops working when it expires, when the key that minted it is revoked, when the sandbox is deleted, or when the sandbox has secrets.
Error code When
sandbox_has_secrets The sandbox was created with secrets. Create a sandbox without secrets.

Coding agents

Every sandbox runs Claude Code and OpenCode. An agent works in the sandbox with its shell, files, desktop and browser. It uses your own API key or subscription, and the model’s usage is billed there. See Run a coding agent in a sandbox for credentials.

The sandbox must be running. A sandbox runs up to one conversation at a time per GiB of memory: 2 on small, 4 on standard, 8 on large, 16 on xl. A conversation runs one turn at a time, and a prompt sent while a turn runs waits in a queue.

agent_prompt

Sends a task to a conversation and waits up to wait_seconds for the turn to end.

Parameter Type Description Default
sandbox string Required.
prompt string Required. The task, up to 262,144 characters.
conversation string Continue this conversation. the most recent conversation
new boolean Start a new conversation. false
harness claude, opencode claude is Claude Code. A harness that differs from the most recent conversation’s starts a new conversation. With conversation, it must match. claude
model string Claude Code: sonnet, opus, haiku, or a full model name. OpenCode: provider/model, for example anthropic/claude-sonnet-4-5, or an opencode/… model, which needs no key. The conversation keeps it for later turns. the harness’s default
wait_seconds integer 0 to 300. 0 returns at once. 60

Returns conversation, turn, status, events and next_after. events holds the turn’s events so far. If status is running or queued, the turn has not ended: call agent_conversations with conversation and after set to next_after to read the rest.

Event type Fields
prompt text, model
message text: the agent’s words.
tool_call id, name, input
tool_result id, output (cut at 65,536 characters), error
turn_finished status (finished, interrupted or failed), input_tokens, output_tokens
error code, message

Every event also has seq, at and turn. Values of the sandbox’s secrets are masked.

A refused prompt is a tool error with the API’s code and message: credentials_missing, not_running, agent_unavailable, too_many_turns, conversation_not_found, unknown_harness, harness_mismatch or unknown_model. See div agent for what to do about each.

agent_conversations

Lists the sandbox’s conversations, or returns one conversation’s events.

Parameter Type Description Default
sandbox string Required.
conversation string Return this conversation’s events instead of the list. none
after integer With conversation: return events after this seq. 0

Without conversation, returns the conversations, most recently active first. Each has id, harness, model, status (idle, running, queued, failed or interrupted), turns, queued, preview, created_at and updated_at.

With conversation, returns events, the conversation’s status and next_after. A turn has ended when its turn_finished event arrives. Call again with after set to next_after to read newer events.

Not available as tools

esc