Agents
Run coding agents inside a Space.
Run coding agents inside a Space.
| Tool | Description |
|---|---|
agent_start | Start a coding agent in the Space. |
agent_message | Send a follow-up to an agent run. |
agent_events | Read an agent run's events after a cursor. |
agent_status | Read an agent run's status and result. |
agent_interrupt | Interrupt an agent run's current turn. |
agent_stop | Stop an agent run. |
agent_list | List agent runs in the Space. |
agent_capabilities | Report what the agent harnesses support. |
Start a coding agent in the Space.
Installs the harness if needed (pinned, checksum-verified), gives it the Space's own MCP tools plus any mcp_servers, and runs it over the Agent Client Protocol as a detached spacesd process with auto-approved permissions (the Space is the sandbox). The run survives this server restarting or the connection dropping. Returns a run_id immediately: follow it with agent_events (cursor) or agent_status, continue it with agent_message, cancel a turn with agent_interrupt. Keys: env_from_host names provider key variables from this server's environment; host credential files are never copied.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:agent_start; destructive |
| Swift SDK | space.agents.start(...) |
| Rust | Agents::start |
| Parameter | Type | Default | Description |
|---|---|---|---|
agent | "claude-code" | "gemini-cli" | "google-antigravity" | "goose" | "hermes" | "openai-codex" | "openclaw" | "opencode" | "pi" | required | Harness id. agent_capabilities lists what each needs. |
base_url | string | none | A custom model endpoint base URL (a proxy or compatible server). |
branch | string | none | Branch or tag for repo. |
cwd | string | none | Working directory in the Space. Default: the run's own. |
env | map of string | {} | More environment for the agent, for example {"HERMES_HOME": "/home/cua/bot"}. Stored 0600 in the run and redacted from its output; name provider keys in env_from_host instead, so their values never pass through the conversation. |
env_from_host | string[] | [] | Provider key variables to forward from this server's environment, for example ["ANTHROPIC_API_KEY"]. Names only; values never pass through the conversation. |
exit_when_idle | boolean | false | Stop (resumably) once the prompt is answered. Default false. |
home | string | none | Run as this persistent agent: its home in the Cua Volume (agents/<home>/) is restored into the Space first and saved after every turn, the harness keeps its memory there, and the agent gets the cua bridge (notify_user, the drive). Creates the persistent agent (this harness, this Space) when it does not exist yet. Default: a one-off run whose state lives only in the Space. |
mcp_servers | object[] | [] | Extra MCP servers. The Space's own tools are always included. |
mcp_servers[].args | string[] | [] | Its arguments. |
mcp_servers[].command | string | null | Command run inside the Space. |
mcp_servers[].name | string | required | Name the agent sees. |
mcp_servers[].url | string | null | http(s):// URL. |
model | string | none | Model id. |
prompt | string | required | The task. |
repo | string | none | Git URL cloned into the working directory first. |
show | boolean | false | Open a terminal on the Space's desktop following the run. Default false. |
space | string | required | Space id or name. |
JSON: run_id, agent, space, process_tag, cwd, notes and hint.
invalid_argument, not_found, ambiguous_sandbox, agent
Send a follow-up to an agent run.
Continues the same session. While a turn runs the message is queued (or, with force=true, the turn is interrupted first); a run whose runner exited is restarted and resumes its session.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:agent_message; destructive |
| Swift SDK | AgentRun.send(_:) |
| Rust | Agents::send |
| Parameter | Type | Default | Description |
|---|---|---|---|
force | boolean | false | Interrupt a running turn first instead of queueing. Default false. |
run_id | string | required | run_id from agent_start. |
space | string | required | Space id or name. |
text | string | required | The message. |
JSON: delivered, run_id, status, phase and reason.
invalid_argument, not_found, ambiguous_sandbox, agent
Read an agent run's events after a cursor.
Normalized events (install, session, turn_started, message, thought, tool_call, tool_update, plan, usage, permission, turn_ended, error, exited, ...) after cursor. Pass the returned cursor back to continue; caught_up=true means nothing more is written yet. The same kinds for every harness.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:agent_events, in spaces:readonly; read-only, idempotent |
| Swift SDK | AgentRun.events(cursor:) |
| Rust | Agents::events |
| Parameter | Type | Default | Description |
|---|---|---|---|
cursor | integer | 0 | cursor from the previous call. Default 0 (the start). At least 0. |
max | integer | 100 | Most events to return. Default 100. At least 0. |
raw | boolean | false | Include each event's raw ACP payload. Default false. |
run_id | string | required | run_id from agent_start. |
space | string | required | Space id or name. |
JSON: run_id, status, phase, events (each seq, ts_ms, turn, kind, and text, tool_id, tool_title, tool_kind, tool_status, stop_reason when present; category: message, user, activity or hidden, and a one-line summary for activity; raw on request), cursor and caught_up.
invalid_argument, not_found, ambiguous_sandbox, agent
Read an agent run's status and result.
status is running, idle, failed, crashed or unknown ('unknown' is never a guess). Includes the last turn's result (final text, stop reason, usage) and a rendered output tail. Read from files in the Space; never disturbs the run.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:agent_status, in spaces:readonly; read-only, idempotent |
| Swift SDK | AgentRun.status() |
| Rust | Agents::status |
| Parameter | Type | Default | Description |
|---|---|---|---|
run_id | string | required | run_id from agent_start. |
space | string | required | Space id or name. |
tail | integer | 40 | Rendered output lines to return. Default 40. At least 0. |
JSON: run_id, agent, status, phase, reason, turn, alive, accepts_message, summary, created_at, result (text, stop_reason, usage, error, tool_calls), output_tail and space.
invalid_argument, not_found, ambiguous_sandbox, agent
Interrupt an agent run's current turn.
Cancels the turn in flight (ACP session/cancel); the session stays open for agent_message.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:agent_interrupt; destructive |
| Swift SDK | AgentRun.interrupt() |
| Rust | Agents::interrupt |
| Parameter | Type | Default | Description |
|---|---|---|---|
run_id | string | required | run_id from agent_start. |
space | string | required | Space id or name. |
JSON: run_id, interrupted and status.
invalid_argument, not_found, ambiguous_sandbox, agent
Stop an agent run.
Ends the run, then verifies its process is gone; reports stopped=false rather than claiming success.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:agent_stop; destructive |
| Swift SDK | AgentRun.stop() |
| Rust | Agents::stop |
| Parameter | Type | Default | Description |
|---|---|---|---|
run_id | string | required | run_id from agent_start. |
space | string | required | Space id or name. |
JSON: run_id, stopped, alive and reason.
invalid_argument, not_found, ambiguous_sandbox, agent
List agent runs in the Space.
Every run in the Space, newest first, including runs another client started.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:agent_list, in spaces:readonly; read-only, idempotent |
| Swift SDK | space.agents.list() |
| Rust | Agents::list |
| Parameter | Type | Default | Description |
|---|---|---|---|
space | string | required | Space id or name. |
JSON: {"space", "runs"}, each run with run_id, agent, status, phase, reason, turn, alive, accepts_message, summary, created_at and label.
invalid_argument, not_found, ambiguous_sandbox, agent
Report what the agent harnesses support.
Every harness: readiness, what it installs, which key variables it reads, which endpoint wire formats it takes, and its known limits; plus the event kinds and statuses.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:agent_capabilities, in spaces:readonly; read-only, idempotent |
| Swift SDK | space.agents.harnessCapabilities() |
| Rust | agents::capabilities |
No parameters.
JSON: protocol, statuses, event_kinds, harnesses (each id, name, ready, installs, keys, endpoint_wires, sandbox_mcp, interactive_cli, notes), forwardable_env and runner.