Coding agents
Run coding agents (Claude Code, Codex, Gemini CLI, OpenCode, ...) inside any sandbox.
Run coding agents (Claude Code, Codex, Gemini CLI, OpenCode, ...) inside any sandbox.
sandbox.agents() (or guest.agents()) runs a harness over the Agent Client Protocol: normalized events, follow-ups, interrupts and results. Runs outlive the handle that started them.
Methods of Sandbox.
Sandbox.agents#Coding agents inside this sandbox (needs cua-spacesd): run a harness over ACP, stream normalized events, follow up, interrupt, collect results; runs outlive this handle.
async def agents(self) -> AgentsReturns Agents ยท Async ยท Raises CuaError
Methods of SpacesdClient.
SpacesdClient.agents#Coding agents in this guest.
async def agents(self) -> AgentsReturns Agents ยท Async ยท Raises CuaError
Agents#Agent runs in one sandbox.
Returned by Sandbox.agents, SpacesdClient.agents.
| Method | Description |
|---|---|
ensure | Installs harnesses or apps (["claude-code", "blender"]: harness ids or installable ids) now; returns the progress lines. |
get | A handle for an existing run (started by any client). |
list | Every run in the sandbox, newest first. |
run | Starts harness on prompt and returns at once; the run lives in the sandbox (fire and forget) until it is stopped. |
Agents.ensure#Installs harnesses or apps (["claude-code", "blender"]: harness
ids or installable ids) now; returns the progress lines.
async def ensure(self, ids: List[str]) -> List[str]| Parameter | Type | Default |
|---|---|---|
ids | Vec<String> | required |
Returns Vec<String> ยท Async ยท Raises CuaError
Agents.get#A handle for an existing run (started by any client).
async def get(self, run_id: str) -> AgentRun| Parameter | Type | Default |
|---|---|---|
run_id | String | required |
Returns AgentRun ยท Async ยท Raises CuaError
Agents.list#Every run in the sandbox, newest first.
async def list(self) -> List[AgentRunInfo]Returns Vec<AgentRunInfo> ยท Async ยท Raises CuaError
Agents.run#Starts harness on prompt and returns at once; the run lives in
the sandbox (fire and forget) until it is stopped.
async def run(self, harness: str, prompt: str, options: Optional[AgentRunOptions]) -> AgentRun| Parameter | Type | Default |
|---|---|---|
harness | String | required |
prompt | String | required |
options | Option<AgentRunOptions> | required |
Returns AgentRun ยท Async ยท Raises CuaError
AgentRun#One run.
Returned by Agents.get, Agents.run.
| Method | Description |
|---|---|
artifacts | Files the run created or changed in its working directory. |
events | Events after cursor (0: from the start), at most max. |
interrupt | Cancels the turn in flight; the session stays open. |
remove | Stops the run and deletes its directory (secrets included). |
result | The last turn's outcome. |
send | A follow-up in the same session (queued while a turn runs). |
status | |
stop | Stops the run and verifies its process is gone. |
wait | Waits until no turn is running (at most timeout_ms), then returns the result. |
| Accessor | Returns | Description |
|---|---|---|
harness() | String | |
run_id() | String |
AgentRun.artifacts#Files the run created or changed in its working directory.
async def artifacts(self) -> List[AgentArtifact]Returns Vec<AgentArtifact> ยท Async ยท Raises CuaError
AgentRun.events#Events after cursor (0: from the start), at most max.
async def events(self, cursor: int, max: Optional[int]) -> AgentEventPage| Parameter | Type | Default |
|---|---|---|
cursor | u64 | required |
max | Option<u32> | required |
Returns AgentEventPage ยท Async ยท Raises CuaError
AgentRun.interrupt#Cancels the turn in flight; the session stays open.
async def interrupt(self) -> AgentRunInfoReturns AgentRunInfo ยท Async ยท Raises CuaError
AgentRun.remove#Stops the run and deletes its directory (secrets included).
async def remove(self) -> NoneAsync ยท Raises CuaError
AgentRun.result#The last turn's outcome.
async def result(self) -> AgentRunResultReturns AgentRunResult ยท Async ยท Raises CuaError
AgentRun.send#A follow-up in the same session (queued while a turn runs).
async def send(self, text: str, files: Optional[List[AgentFile]]) -> AgentRunInfo| Parameter | Type | Default |
|---|---|---|
text | String | required |
files | Option<Vec<AgentFile>> | required |
Returns AgentRunInfo ยท Async ยท Raises CuaError
AgentRun.status#async def status(self) -> AgentRunInfoReturns AgentRunInfo ยท Async ยท Raises CuaError
AgentRun.stop#Stops the run and verifies its process is gone.
async def stop(self) -> AgentRunInfoReturns AgentRunInfo ยท Async ยท Raises CuaError
AgentRun.wait#Waits until no turn is running (at most timeout_ms), then returns
the result.
async def wait(self, timeout_ms: Optional[int]) -> AgentRunResult| Parameter | Type | Default |
|---|---|---|
timeout_ms | Option<u64> | required |
Returns AgentRunResult ยท Async ยท Raises CuaError
AgentRunOptions record#Options for Agents.run. Every field is optional.
| Field | Type | Default | Description |
|---|---|---|---|
cwd | Option<String> | None | Working directory in the sandbox (default: the run's own). |
repo | Option<String> | None | Git URL cloned into the working directory first. |
branch | Option<String> | None | |
env | HashMap<String, String> | [:] | Env for the agent only (API keys): written 0600 in the run, redacted from its event log, never in argv. |
env_from_host / envFromHost | Vec<String> | [] | Provider key variables copied from THIS process's environment (["ANTHROPIC_API_KEY"]); only known provider key names. |
model | Option<String> | None | Model id. |
base_url / baseUrl | Option<String> | None | A custom model endpoint (proxy, gateway, compatible server). |
wire | Option<String> | None | Its wire format: anthropic, openai-responses, openai-chat, gemini (default: the harness's own). |
mcp_servers / mcpServers | Vec<AgentRunMcpServer> | [] | |
sandbox_mcp / sandboxMcp | Option<bool> | None | Give the agent the sandbox's own MCP (cua-driver). Default true. |
skills | Option<bool> | None | Copy the cua skills into the harness. Default true. |
install | Option<bool> | None | Install what the harness needs. Default true. |
files | Vec<AgentFile> | [] | |
exit_when_idle / exitWhenIdle | bool | false | Stop (resumably) once the queue is empty: fire-and-forget. |
label | Option<String> | None |
AgentRunMcpServer record#An MCP server a run's agent gets: url (streamable HTTP, as reachable
from inside the sandbox) or command (stdio, run in the sandbox).
| Field | Type | Default | Description |
|---|---|---|---|
name | String | Name the agent sees. | |
url | Option<String> | None | |
headers | HashMap<String, String> | [:] | Header values (secrets allowed: they travel like env keys). |
command | Option<String> | None | |
args | Vec<String> | [] | |
env | HashMap<String, String> | [:] |
AgentFile record#A file for the first prompt or a follow-up.
| Field | Type | Default | Description |
|---|---|---|---|
name | String | File name in the run's attachments/. | |
bytes | Vec<u8> |
AgentEvent record#One normalized event.
| Field | Type | Default | Description |
|---|---|---|---|
seq | u64 | ||
ts_ms / tsMs | u64 | ||
turn | u32 | ||
kind | String | message, thought, tool_call, tool_update, plan, usage, permission, turn_started, turn_ended, install, error, exited, ... (see harnesses()). | |
text | Option<String> | ||
tool_id / toolId | Option<String> | ||
tool_title / toolTitle | Option<String> | ||
tool_kind / toolKind | Option<String> | ||
tool_status / toolStatus | Option<String> | ||
stop_reason / stopReason | Option<String> | ||
category | String | How a conversation view shows it: message (the agent's words), user (the prompt as the agent got it), activity (a muted one-line row: install, thinking, tools, plan, turn end, notice, error, exit) or hidden. See AgentTranscript. | |
summary | Option<String> | One short line for an activity event. | |
line | Option<String> | One human-readable line, when the kind has one. | |
json | String | The event as written (ACP payload included), JSON. |
AgentEventPage record#A page of events.
Returned by AgentRun.events.
| Field | Type | Default | Description |
|---|---|---|---|
events | Vec<AgentEvent> | ||
cursor | u64 | Pass back to continue. | |
caught_up / caughtUp | bool | Nothing more is written yet. |
AgentRunInfo record#A run's state.
Returned by AgentRun.interrupt, AgentRun.send, AgentRun.status, AgentRun.stop, Agents.list.
| Field | Type | Default | Description |
|---|---|---|---|
run_id / runId | String | ||
harness | Option<String> | ||
status | String | running, idle, failed, crashed, unknown. | |
phase | String | installing, starting, working, waiting, exited, ... | |
reason | String | ||
turn | u32 | ||
alive | Option<bool> | ||
accepts_message / acceptsMessage | bool | A follow-up sent now starts the next turn (not mid-turn). | |
prompt | Option<String> | ||
label | Option<String> | ||
created_at / createdAt | Option<f64> | Unix seconds. | |
json | String |
AgentRunResult record#What the last turn produced.
Returned by AgentRun.result, AgentRun.wait.
| Field | Type | Default | Description |
|---|---|---|---|
run_id / runId | String | ||
status | String | ||
turn | u32 | ||
text | String | The agent's messages in the last turn. | |
stop_reason / stopReason | Option<String> | ||
usage_json / usageJson | Option<String> | ||
error | Option<String> | ||
tool_calls / toolCalls | u32 |
AgentArtifact record#A file the run created or changed.
Returned by AgentRun.artifacts.
| Field | Type | Default | Description |
|---|---|---|---|
path | String | ||
size | u64 | ||
modified_ms / modifiedMs | u64 |
agent_harnesses#The harnesses, their readiness, installs, key variables and limits, as JSON.
def agent_harnesses() -> strReturns String
AgentTranscript#A run's events folded into conversation items, the same rule in every
language: the agent's message chunks join into message items, the
prompt is a user item (never repeated as agent text), and consecutive
activity of one turn folds into one activity group. Absorbing an event
twice changes nothing, so a poll can re-read a page.
| Method | Description |
|---|---|
new | An empty transcript. |
absorb | Adds events from AgentRun.events. |
absorb_json | Adds the events of an agent_events result (Space.agent_events, the MCP tool), or a JSON array of events. |
note | Adds a line the app itself produced (a start note, "queued") as an activity step of turn. |
| Accessor | Returns | Description |
|---|---|---|
cursor() | u64 | The highest agent_events cursor absorbed: pass it back to read on. |
items() | Vec<AgentTranscriptItem> | The items so far. |
preview() | Option<String> | The agent's last message on one line (a roster preview), None before it has said anything. Activity is never a preview. |
revision() | u64 | Changes whenever the items do. |
AgentTranscript.new#An empty transcript.
AgentTranscript()Returns AgentTranscript
AgentTranscript.absorb#Adds events from AgentRun.events.
def absorb(self, events: List[AgentEvent]) -> None| Parameter | Type | Default |
|---|---|---|
events | Vec<AgentEvent> | required |
AgentTranscript.absorb_json#Adds the events of an agent_events result (Space.agent_events,
the MCP tool), or a JSON array of events. Returns the page's
cursor (also kept, see AgentTranscript.cursor) when it has one.
def absorb_json(self, json: str) -> Optional[int]| Parameter | Type | Default |
|---|---|---|
json | String | required |
Returns Option<u64> ยท Raises CuaError
AgentTranscript.note#Adds a line the app itself produced (a start note, "queued") as an
activity step of turn.
def note(self, turn: int, text: str) -> None| Parameter | Type | Default |
|---|---|---|
turn | u32 | required |
text | String | required |
AgentTranscriptItem record#One item of an AgentTranscript.
Returned by AgentTranscript.items.
| Field | Type | Default | Description |
|---|---|---|---|
kind | String | message (a bubble or prose), user (the prompt as the agent got it; skip it when the app shows what the user typed) or activity (a muted, collapsible group of one-line steps). | |
turn | u32 | Turn number (0 before the first prompt). | |
text | String | The message or prompt; for activity, the group summary (5 steps). | |
steps | Vec<String> | activity only: one line per step. |
agent_event_category#The category of an event kind: message, user, activity or
hidden (the rule AgentEvent.category and AgentTranscript use).
def agent_event_category(kind: str) -> str| Parameter | Type | Default |
|---|---|---|
kind | String | required |
Returns String