Agent, teleport and storage tools

Run agents in a Space, teleport apps, and use Keyvault and Cua Volume: the tools with their parameters, results and errors.

Agents#

Run coding agents inside a Space.

agent_start#

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: provider keys saved in Cua Spaces (Settings → Connections) reach the runs whose harness reads them; env_from_host names provider key variables from this server's environment; host credential files are never copied.

Parameters#

Result#

JSON: run_id, agent, space, process_tag, cwd, notes and hint.

Errors#

invalid_argument, not_found, ambiguous_sandbox, agent

Notes#

• Runs auto-approved: the Space is the sandbox, which is why approvalsAreEnforced is false.

agent_message#

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.

Parameters#

Result#

JSON: delivered, run_id, status, phase and reason.

Errors#

invalid_argument, not_found, ambiguous_sandbox, agent

agent_events#

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.

Parameters#

Result#

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.

Errors#

invalid_argument, not_found, ambiguous_sandbox, agent

agent_status#

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.

Parameters#

Result#

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.

Errors#

invalid_argument, not_found, ambiguous_sandbox, agent

agent_interrupt#

Interrupt an agent run's current turn.

Cancels the turn in flight (ACP session/cancel); the session stays open for agent_message.

Parameters#

Result#

JSON: run_id, interrupted and status.

Errors#

invalid_argument, not_found, ambiguous_sandbox, agent

agent_stop#

Stop an agent run.

Ends the run, then verifies its process is gone; reports stopped=false rather than claiming success.

Parameters#

Result#

JSON: run_id, stopped, alive and reason.

Errors#

invalid_argument, not_found, ambiguous_sandbox, agent

agent_list#

List agent runs in the Space.

Every run in the Space, newest first, including runs another client started.

Parameters#

Result#

JSON: {"space", "runs"}, each run with run_id, agent, status, phase, reason, turn, alive, accepts_message, summary, created_at and label.

Errors#

invalid_argument, not_found, ambiguous_sandbox, agent

agent_capabilities#

Report what the agent harnesses support.

Every harness: readiness (including whether a credential is available, with a hint when not), what it installs, which key variables it reads, which endpoint wire formats it takes, and its known limits; plus the event kinds and statuses.

Parameters#

No parameters.

Result#

JSON: protocol, statuses, event_kinds, harnesses (each id, name, ready (supported and not auth: missing), supported, auth (ok: a key saved in Cua Spaces (Settings → Connections) or one this server can forward with env_from_host; missing: none, so a run needs a sign-in inside its Space; unknown: the harness may be set up through its own config), auth_hint, installs, keys, endpoint_wires, sandbox_mcp, interactive_cli, notes), forwardable_env and runner.

Errors#

invalid_argument

agent_sign_in#

Sign a coding agent in on the Space's computer, the agent's own way.

Only for a person, never for an agent: no MCP server lists or runs it. Signs Claude Code or Codex in on the Space's own computer with the agent's official sign-in (claude auth login, codex login --device-auth), so the sign-in stays in that computer's agent config and Cua never holds it. start shows a link (and Codex's code) for the person to open in their own browser; the person finishes it in their own browser.

Parameters#

Result#

JSON: {"space", "agent", "state"}; state is not_signed_in, signing_in (with url, code (Codex: type it on that page) and paste_code (Claude Code: the person pastes the page's code back with action code)), signed_in, failed (with reason) or expired.

Errors#

invalid_argument, not_found, ambiguous_sandbox, agent

agent_threads#

List the recent Claude Code, Codex and Hermes chats on this computer. For a person only.

Only for a person, never for an agent: no MCP server lists or runs it, and the daemon answers only this computer's own user (never a relay caller or a Space's agent). Reads the coding agents' own stores on this computer read-only (Claude Code's projects folder, Codex's sessions, Hermes's state.db) and returns only each chat's title, folder and time; nothing is kept or sent anywhere. A store that is missing or unreadable adds nothing.

Parameters#

Result#

JSON: threads, newest first, each agent (harness id), id, title (the chat's name, or its first prompt cut to 80 characters), cwd (its folder, or null), last_active_ms and resume (the agent's own command that continues it in a terminal, as argv).

Errors#

invalid_argument, permission_denied

agent_thread_read#

Read one of the recent Claude Code, Codex or Hermes chats on this computer. For a person only.

Only for a person, never for an agent: no MCP server lists or runs it, and the daemon answers only this computer's own user. Reads one chat from the agent's own store, read-only: what the person typed and the agent's replies, without tool calls, tool output, thinking or the agent's own injected instructions. Call it once the person picked the chat; continue it with agent_start's resume_session.

Parameters#

Result#

JSON: thread (as in agent_threads), messages (oldest first, each key, role (person or agent), text (cut to 8 KiB), ts_ms, and cut when cut) and earlier_omitted (older messages left out).

Errors#

invalid_argument, permission_denied, not_found

Persistent agents#

Named agents whose memory outlives their Space: homes in Cua Volume, routines, notifications, pause and resume, access to the user's computers.

agent_add#

Create a named agent whose memory outlives its Space.

A persistent agent is an agent member of the Space it works in, with its memory in its home in the Cua Volume (agents/<name>/), restored before each run and saved after each turn. People @mention it in the Space's thread (thread_post) and it answers there; it sleeps until a message or a schedule wakes it. Its harness keeps its memory in the home (Claude Code auto memory, Codex memories, Hermes MEMORY.md, the OpenClaw workspace). With every_minutes, daily_at or weekly_on and a prompt it also gets a schedule. With sessions (1-8) it works on up to that many tasks at once, each in its own run; session 1 alone writes its home, the others start from the home as last saved. durable, on other than local and once are not available yet and are refused. Inside the Space the agent gets the cua bridge: the thread, notify_user, the drive, and the user's computers it was granted.

Parameters#

Result#

JSON: the agent record: name, harness, space, model, base_url, env_from_host, paused, space_state and created_ms; as a member of its Space also sessions, policy {durable, on, once, guard}, added_by, member_since_ms, status and, with a schedule, schedule (the routine).

Errors#

invalid_argument, not_found, ambiguous_sandbox, agent

persistent_agent_list#

List persistent agents.

Every persistent agent of this computer's cua home, with its Space, its current run and when its home was last saved.

Parameters#

No parameters.

Result#

JSON: {"agents"}, each with name, harness, space, paused, space_state, run_id, saved_ms and last_error.

Errors#

invalid_argument

agent_remove#

Forget a persistent agent.

Stops its run, removes its routines, closes its open thread tasks and takes it out of its Space. Its home (agents/<name>/) stays in the Cua Volume unless keep_home is false. The thread keeps what it wrote.

Parameters#

Result#

JSON: removed (the record) and home_deleted. By default the home stays in the Cua Volume.

Errors#

invalid_argument, agent

agent_send#

Give a persistent agent a turn.

A follow-up to the agent's idle run, or a new run with its home restored when it has none. Refused while a turn runs (never interrupts) and while paused. Follow the run with agent_events on the agent's Space.

Parameters#

Result#

JSON: run_id, started (a new run, with the home restored) and restored (files, bytes, millis).

Errors#

invalid_argument, not_found, ambiguous_sandbox, agent, lease_held

persistent_agent_save#

Save a persistent agent's home now.

Saves the agent's home from its Space into the Cua Volume now (the daemon also saves after every turn): only files whose SHA-256 changed move.

Parameters#

Result#

JSON: files, bytes, unchanged, removed, blocked (files the secret scanner kept out) and millis.

Errors#

invalid_argument, agent, secret_detected

agent_pause#

Pause a persistent agent: its run, its routines and its Space.

One call: stops the run, saves the home, releases the home's lease, keeps the agent's routines from firing, and suspends its Space when it is local. A cloud Space cannot be suspended, so pausing releases it after the home is saved; agent_resume creates it again from the same image and restores the home. Apps open in a released cloud Space do not come back. The user's own computers are never suspended.

Parameters#

Result#

JSON: stopped_run, saved (the home save), space_state (suspended, released or running) and millis.

Errors#

invalid_argument, agent, sandbox

agent_resume#

Resume a paused persistent agent.

Resumes a suspended local Space, or creates a released cloud Space again from the same image, restores the home and lets routines fire again. With prompt, starts a run on it.

Parameters#

Result#

JSON: space (it can change when a cloud Space is created again), recreated, restored, run_id and ready_ms (from the call to the home being back in a ready Space).

Errors#

invalid_argument, agent, sandbox

agent_schedule_add#

Schedule a recurring turn for a persistent agent.

Fired by cua daemon whether or not an app is open, as a turn of the agent ([routine] <title>: <prompt>). A routine never interrupts a turn: a busy or paused agent skips that slot. A daemon that was asleep fires a missed routine once on waking.

Parameters#

Result#

JSON: the routine: id, botID (the agent), title, prompt, schedule, isEnabled and createdAt.

Errors#

invalid_argument

agent_schedule_list#

List routines.

Routines with their next firing and what the last one did.

Parameters#

Result#

JSON: {"routines"}, each with id, botID, title, prompt, schedule, label, isEnabled, lastFiredAt, lastRunID, lastOutcome and next_fire.

Errors#

invalid_argument

agent_schedule_remove#

Delete a routine.

Parameters#

Result#

JSON: removed (the id).

Errors#

invalid_argument

agent_schedule_set_enabled#

Turn a routine on or off.

Parameters#

Result#

JSON: the routine.

Errors#

invalid_argument

notify_user#

Tell the user something in the Cua app.

Posts a notification the Cua app shows ("Your research is ready"). Agents inside a Space get the same tool on their cua bridge.

Parameters#

Result#

JSON: notified and id.

Errors#

invalid_argument

notifications_list#

Read the notifications feed.

The feed the Cua app turns into system notifications: turn ends of persistent agents, notify_user calls, access requests and failures. It persists while no app is open.

Parameters#

Result#

JSON: {"notifications"}, newest first, each with id, at_ms, agent, kind (turn_ended, message, approval, error), title, body, run_id, space and read.

Errors#

invalid_argument

notifications_ack#

Mark notifications read.

Parameters#

Result#

JSON: marked (how many changed).

Errors#

invalid_argument

computer_access_grant#

Let a persistent agent use one of the user's computers.

Lets one persistent agent use one of the user's computers (its computer-use tools, through the agent's bridge). Asks the user for presence (Touch ID or passphrase) first. Other agents of the account get nothing.

Parameters#

Result#

JSON: the grant: id, agent, machine, created_ms, expires_ms.

Errors#

invalid_argument, not_confirmed

computer_access_revoke#

Take back a persistent agent's access to a computer.

Takes the access back at once: the agent's next call is refused. No presence needed.

Parameters#

Result#

JSON: revoked (how many grants).

Errors#

invalid_argument

computer_access_list#

List per-agent computer access.

Which agents may use which of the user's computers, and the audited record of grants, uses and refusals.

Parameters#

Result#

JSON: {"grants"} (each id, agent, machine, created_ms, expires_ms, revoked) and, with audit, audit (newest first: ts_ms, principal, action, path (the computer), detail) plus audit_verified.

Errors#

invalid_argument

Session teleport#

Move a signed-in app session from this computer into a Space.

teleport_manifest#

Describe what a session teleport would move.

Read on this computer from the app's own provider: items, sizes, which are sensitive and which are checked by default. With space, also reports whether the Space can import the app.

Parameters#

Result#

JSON: app, display_name, scope, items (each relative_path, label, estimated_bytes, is_sensitive, is_checked_by_default), total_estimated_bytes, notes; with space, a receiver (supported, limitation, app_installed, supported_apps).

Errors#

invalid_argument, not_found, ambiguous_sandbox, host_capability_missing

Notes#

• The manifest is the thing an Approval is minted from: the SDK will not send a teleport the caller has not seen a manifest for.

teleport_app#

Move an app session into the Space.

Moves the app's signed-in session into the Space, but only through the Cua Keyvault and only with the user's consent. This tool never delivers on its own: the first call files a Keyvault access request and returns a request_id; the user approves it in Cua (Touch ID or the login password) or an unattended rule matches; a later call with the same request_id has the Keyvault broker perform the delivery over the daemon's authenticated channel. Without include the manifest's default-checked items move, never everything.

Parameters#

Result#

JSON. First call: consent_required: true, a request_id, would_send and approve. Retry with request_id once the user approved: moved: true with transferred_paths (what the Space imported), import_ids and expires_ms; or still consent_required while pending; or an error with the Keyvault code (requires_cua_app, denied, disabled) when it cannot proceed.

Errors#

invalid_argument, not_found, ambiguous_sandbox, spacesd_not_available, capability_missing, host_capability_missing, teleport_refused, transfer_failed

Notes#

• Works on every provider. A comment in the SDK claiming teleport was cloud-only was stale and was a real bug: callers were being told to provision a metered Space for work a free Local Space does.
• Consent is owned by the Keyvault broker, not this tool: the automation caller is treated as an unverified third party, so a delivery needs a live consent or an audited unattended rule and can never be self-approved (red-team E2).

Keyvault#

Use the user's saved credentials in a Space, only with their approval.

request_site_login#

Sign in to a site in the Space with the user's saved password.

Signs in to a website in the Space's browser with a password the user saved in the Cua Keyvault (imported from their browser). The first call files a Keyvault request and returns a request_id; the user approves it in Cua (Touch ID or the login password), once per sign-in by default. Call again with the same space, url and request_id: the Keyvault checks the page is on the saved login's exact origin, types the username and password through the Space's cua-driver, submits the form and returns what it did, never the password. Pass the browser tab you opened (session, target_id, tab_id from get_browser_state on the same Space) to sign in there; without one the Keyvault opens its own browser in the Space on url and returns its target_id and tab_id. agent names the persistent agent asking, shown to the user.

Parameters#

Result#

JSON. First call: status: "pending", a request_id, site and space. Retry with request_id: status: "filled" with site, origin, username_hint (masked), submitted, page_url and the browser target_id/tab_id it signed in; status: "pending" while the user decides; status: "denied" when they declined. Never the password.

Errors#

invalid_argument, not_found, ambiguous_sandbox, spacesd_not_available, capability_missing, login_refused

Notes#

• The password never reaches the caller: the Keyvault fills the form through the Space's cua-driver and returns only a masked username.
• Approval is required by default for every sign-in (one use per approval); only an unattended rule the user wrote skips it.

Cua Volume#

Read and write the volume every Space and agent shares, decide who may reach what, and see where it is stored and how it syncs.

volume_ls#

List a folder of the Cua Volume.

Cua Volume is one versioned drive per account, shared by every Space and agent: public/ (shared reference, read by everyone), agents/<agent>/ (a persistent agent's home: memory, outputs, inbox) and spaces/<space>/ (per-Space scratch). As the user (the default) you see everything. With as_agent (and in_space) you see exactly what that agent sees: it reads public/, writes its own home and its Space's folder, and anything wider needs a grant the user approves.

Parameters#

Result#

JSON: path, principal and entries (each path, name, folder, size, modified_ms, etag, mode, and sync when a file has something to say: state pending_upload, conflict (with conflict_path) or conflict_copy, and written_by when another device wrote it last).

Errors#

invalid_argument, forbidden, volume_backend

volume_read#

Read a file from the Cua Volume.

Reads at most 8 MiB. Text comes back as utf8, anything else as base64.

Parameters#

Result#

JSON: path, size, etag, version, modified_ms, encoding (utf8 or base64), content, and sync while the drive's services run (state synced, pending_upload, conflict or conflict_copy; written_by, conflict_path).

Errors#

invalid_argument, forbidden, volume_backend

volume_write#

Write a file to the Cua Volume.

Every write is a new version (history is kept). if_etag makes it a compare-and-swap, create_only makes it create-only. Writes under agents/ are scanned for secrets and refused by kind and line; keep credentials in the Keyvault.

Parameters#

Result#

JSON: the new version's key, size, etag, version and modified_ms.

Errors#

invalid_argument, forbidden, precondition_failed, secret_detected, volume_backend

volume_delete#

Delete a file from the Cua Volume.

Adds a delete marker; volume_history and volume_restore still reach the old versions.

Parameters#

Result#

JSON: {"deleted": <path>}.

Errors#

invalid_argument, forbidden, precondition_failed, volume_backend

volume_history#

List a Cua Volume file's versions.

Parameters#

Result#

JSON: path and versions (each version, size, modified_ms, deleted, latest), newest first.

Errors#

invalid_argument, forbidden, volume_backend

volume_restore#

Restore an old version of a Cua Volume file.

Writes the old version's content as a new version, so the restore itself can be undone.

Parameters#

Result#

JSON: the new current version's key, size, etag, version and modified_ms.

Errors#

invalid_argument, forbidden, secret_detected, volume_backend

volume_grant#

Grant an agent or Space more Cua Volume access.

Only for the user: widens an agent's or a Space's access past the defaults (an agent reads public/ and writes its own home and its Space's folder). The user confirms with presence (Touch ID, the login password or the vault passphrase) before anything widens; a grant that widens nothing is refused.

Parameters#

Result#

JSON: the grant (id, principal, prefix, mode, created_ms, expires_ms, revoked, note).

Errors#

invalid_argument, not_confirmed, forbidden

volume_revoke#

Revoke a Cua Volume grant.

Parameters#

Result#

JSON: the revoked grant.

Errors#

invalid_argument, forbidden

volume_grants#

List Cua Volume grants.

Parameters#

Result#

JSON: {"grants": [...]}, live grants only unless all.

Errors#

invalid_argument, forbidden

volume_request_access#

Ask the user for more Cua Volume access.

Files a request the user sees in Cua; it grants nothing by itself. Poll volume_ls or volume_read to see when access arrives.

Parameters#

Result#

JSON: the request (id, principal, prefix, mode, reason, created_ms).

Errors#

invalid_argument, forbidden

volume_requests#

List Cua Volume access requests waiting for the user.

Parameters#

No parameters.

Result#

JSON: {"requests": [...]}.

Errors#

invalid_argument, forbidden

volume_approve#

Approve a Cua Volume access request.

Only for the user, with presence.

Parameters#

Result#

JSON: the grant the request became.

Errors#

invalid_argument, not_confirmed, forbidden

volume_deny#

Decline a Cua Volume access request.

Parameters#

Result#

JSON: {"denied": <request id>}.

Errors#

invalid_argument, forbidden

volume_audit#

Read the Cua Volume audit log.

Every grant, revocation, request, refusal, blocked secret, sync, lease and agent access, from a hash-chained log; an edited or truncated log reports verified=false.

Parameters#

Result#

JSON: events (each seq, ts_ms, principal, action, path, detail), newest first, and verified (with error when the hash chain does not verify).

Errors#

invalid_argument, forbidden

volume_storage#

Show where the Cua Volume keeps its bytes.

Only for the user. Keys are never returned; has_keys says whether the credential store holds them.

Parameters#

No parameters.

Result#

JSON: backend (fs or s3), fs_path, s3 (endpoint, region, bucket, root, path_style), has_keys, cloud_available.

Errors#

invalid_argument, forbidden

volume_storage_set#

Test or change where the Cua Volume keeps its bytes.

Only for the user. Tests the storage first (bucket versioning, list, then write, read back and delete a probe object; retries path-style addressing to tell when a self-hosted store needs it); with dry_run nothing else happens. Otherwise, when the test passes, saves the setting and the keys (credential store) and switches the running drive to it without a restart. The bucket must have versioning on. cloud is refused.

Parameters#

Result#

JSON: ok, reachable, authorized, versioning, detail (a sentence when not ok saying how to fix it), problem (unreachable, bad_keys, forbidden, bucket_missing, versioning_off, path_style_needed) and applied (saved and switched live).

Errors#

invalid_argument, forbidden

volume_mount_status#

Show whether the Cua Volume is mounted as a volume.

Only for the user. The drive can appear as a volume (Finder on macOS, a FUSE mount on Linux); it is off until the user turns it on with volume_mount.

Parameters#

No parameters.

Result#

JSON: enabled, state (off, mounting, mounted, needs_approval, unsupported, error), method (nfs, fuse, fskit, none), path, volume_name, detail, settings_url; plus the Spaces' own: volumes (mounted in a Space: space, mount_path, backend, principal) and volume_errors (each space and error: why a Space has no Cua Volume, for example no /dev/fuse in a container on runc).

Errors#

invalid_argument, forbidden

volume_mount#

Mount the Cua Volume as a volume.

Only for the user. Turns the mount on (kept across restarts) and mounts. Idempotent.

Parameters#

No parameters.

Result#

JSON: the mount status after the attempt (see volume_mount_status).

Errors#

invalid_argument, forbidden

volume_unmount#

Unmount the Cua Volume volume.

Only for the user. Turns the mount off; files still uploading land first.

Parameters#

No parameters.

Result#

JSON: the mount status after unmounting.

Errors#

invalid_argument, forbidden, volume_backend

volume_sync_status#

Show the Cua Volume's sync state across devices.

Devices sharing one bucket learn each other's changes through a change log in the bucket itself. A write that lost to a later one is never dropped: it stays in the file's history and as the visible conflict copy. A persistent agent may call it too (through its bridge): it sees the pending uploads and conflicts of files it can read and its own Space's volume. In a Space it reports this computer's view.

Parameters#

No parameters.

Result#

JSON: device_id, device_name, feed (live, off for a store on this computer, offline when the bucket stops answering, with last_error), poll_interval_ms, last_poll_ms, last_remote_change_ms, pending_uploads, pending_bytes, conflicts (each path, conflict_path, winner_device, loser_device, winner_version, loser_version, ts_ms), devices (each id, name, this_device, last_seen_ms, last_change_ms, changes), last_error, pending (each path, bytes: files still uploading), backend (fs or s3), mount (this computer's mount: off, mounting, mounted, needs_approval, unsupported, error), cache (a bucket's block cache, when there is one) and volumes (the volume mounted in Spaces: each space, mount_path, backend, principal).

Errors#

invalid_argument, forbidden

volume_sync_events#

Wait for Cua Volume sync events.

Only for the user. A long poll: answers at once when events newer than since_seq exist, else waits up to wait_ms for one. Kinds: remote_change, remote_delete, upload_started, upload_done, upload_failed, conflict, error.

Parameters#

Result#

JSON: events (each seq, ts_ms, kind, path, device, size, version, detail) and next_seq.

Errors#

invalid_argument, forbidden

volume_sync_resolve#

Mark a Cua Volume sync conflict as seen.

Only for the user. Clears the conflict from the list; both files stay.

Parameters#

Result#

JSON: {"resolved": <path>}.

Errors#

invalid_argument, forbidden, not_found

volume_cache_stats#

Show the Cua Volume block cache.

Only for the user. Reads of a remote store go through a local block cache; counters are since the runtime started.

Parameters#

No parameters.

Result#

JSON: dir, size_bytes, capacity_bytes, block_bytes, blocks, hits, misses, hit_rate, prefetched_bytes, evictions.

Errors#

invalid_argument, forbidden

volume_cache_set#

Set the Cua Volume block cache's size cap.

Only for the user. Evicts down to the new cap at once; kept across restarts.

Parameters#

Result#

JSON: the cache stats after the change.

Errors#

invalid_argument, forbidden

volume_cache_clear#

Clear the Cua Volume block cache.

Only for the user. Drops every cached block; files stay in the drive.

Parameters#

No parameters.

Result#

JSON: the cache stats after clearing.

Errors#

invalid_argument, forbidden