Reference

Every Spaces tool by category, with parameters, results, errors and approval.

The Spaces contract: 122 tools with the same names and schemas on every surface: cua mcp, cua daemon mcp and the Spaces SDKs. Contract 0.9.0, MCP protocol revision 2025-06-18, transports mcp_stdio and mcp_streamable_http. Experimental: names and shapes can change between minor versions.

Tools#

Space lifecycle#

Register, provision, list and release Spaces.

Commands and files#

Run shell commands and move files in and out of a Space.

Streams and display#

Stream a Space's desktop or windows, and show a Space to the operator.

Services#

Discover and call the MCP services inside a Space.

Agents#

Run coding agents inside a Space.

Persistent agents#

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

Space thread and members#

Each Space's conversation: people and agent members post, an @mention wakes an agent, and anyone can check in from any device.

Session teleport#

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

Keyvault#

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

Hotspot#

Share this computer's network with a Space.

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.

Sharing#

Let other cua.ai accounts watch or edit a Space, through the relay.

Your cloud#

Create Spaces in your own AWS, Google Cloud, Hetzner or Modal account: connect it, check it, and clean up what Cua created there.

Space ids#

Every tool that takes space accepts a Space id or its name.

Approval#

• cua mcp --permissions (or CUA_MCP_PERMISSIONS) gates each tool as spaces:<tool>. spaces:all grants every tool, spaces:readonly only the read-only ones.
• Each tool publishes MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint); clients use them to decide what to confirm. The Approval row of each tool shows them.
• Metered tools () allocate or extend a billed cloud Space. Everything else is free.
• Agent runs are auto-approved inside the Space: the Space is the sandbox. A session teleport needs an approval minted from its manifest, and acknowledge_sensitive for sensitive items.

Errors#

A tool that fails returns a normal result with isError: true, never a protocol error:

{
  "content": [{ "type": "text", "text": "error: <message>" }],
  "isError": true,
  "structuredContent": { "error": { "kind": "<kind>", "message": "<message>" } }
}

Branch on kind; the message is for people. Every tool can return invalid_argument. A tool that takes space can also return not_found and ambiguous_sandbox; one with spacesd requires, spacesd_not_available and capability_missing; one with host requirements, host_capability_missing. Each tool lists the rest.

Error kinds#

invalid_argument#

An argument is missing, malformed or out of range.

Fix: Check the call against the tool's input schema; the message names the argument.

Listed by network_show, network_set, resize_space, space_service, agent_thread_read, thread_join, thread_join_code_create, thread_join_code_cancel, volume_storage_set, volume_cache_set, relay_unregister_space, cloud_connect, cloud_approve, cloud_add_host, cloud_budget, prewarm.

not_found#

No Space, run, window, service, tool or file with that id.

Fix: List what exists first (list_spaces, agent_list, list_space_windows, list_tools).

Listed by network_show, network_log, network_set, space_job, space_service, agent_thread_read, thread_join_code_cancel, volume_sync_resolve, cloud_remove_host.

spacesd_not_available#

The computer answered but runs no cua-spacesd, so the spacesd primitives cannot work.

Fix: Use an image that runs cua-spacesd (for example ghcr.io/trycua/linux:24.04), or reach the Space's own services with list_tools and call_tool.

capability_missing#

The Space's cua-spacesd reports a feature this tool needs as unsupported; the message names it and the driver's limitation.

Fix: Use a Space whose spacesd supports the feature (see the tool's requires).

Listed by space_service.

host_capability_missing#

A prerequisite on this computer is missing: a local runtime, an operator display or app-session providers.

Fix: Set up what the message names (see the tool's host_requires).

wrong_provider#

The operation does not apply to this kind of Space.

Fix: Use a tool that serves the Space's provider (see the tool's providers).

Listed by network_log, network_set, stop_space, resize_space, start_space, space_job.

unauthenticated#

The Space's spacesd or the cua.ai relay rejected the token.

Fix: Re-add the Space with a valid token, or sign in again with cua auth login.

Listed by add_space, list_spaces, share_space, unshare_space, space_shares, relay_register_space, relay_unregister_space.

permission_denied#

The signed-in account may not reach that relay computer.

Fix: Sign in with the account that owns the computer.

Listed by stop_space, start_space, agent_threads, agent_thread_read, thread_import, agent_set_rights, thread_join, thread_join_code_create, thread_join_code_cancel, thread_join_redeem, thread_settings, thread_device_revoke, share_space, unshare_space, relay_unregister_space.

ambiguous_host#

The computer name given to on="host:<name>" fits several of your computers equally well; the message lists them.

Fix: Ask the user which computer they meant, then pass on="host:<computer id>" from the list.

Listed by create_space.

limit_exceeded#

The host is at a capacity limit: two macOS VMs per Mac (Apple's macOS license, enforced by Apple Virtualization) or the host's own Space limit.

Fix: Delete a Space on that host (delete_space), pick another computer, or create a Linux Space instead.

Listed by create_space, cloud_plan, prewarm.

host_capacity#

The machine has no room for another Space now: its VMs are at their memory limit (shared snapshot memory counted once) or CPU limit, or it is low on memory. Nothing was started; the message says which limit and by how much.

Fix: Delete a Space (delete_space), create it smaller (cpus, memory_mb), or create it with on="auto" so another machine takes it.

ambiguous_sandbox#

A short name matches more than one sandbox.

Fix: Use the full id (local:<name> or cloud:<name>).

transfer_failed#

A file transfer did not land, or landed with a different sha256.

Fix: Retry; check free space and permissions at the destination.

Listed by space_write, upload, send_file, download, teleport_app.

teleport_refused#

The teleport consent gate refused: a sensitive item without acknowledge_sensitive, a declined approval, or a Space that cannot import the app.

Fix: Read teleport_manifest, then pass the items to move and acknowledge_sensitive=true for sensitive ones.

Listed by teleport_app.

login_refused#

The Keyvault refused a site login: the user declined, no saved password matches the page's origin, the tab is on another origin, or the Keyvault is locked or off.

Fix: Ask the user to approve the sign-in in Cua, import the site's saved password, or open the site's sign-in page and try again.

Listed by request_site_login.

agent#

An agent run failed outside the transport: install, configuration or a refused message.

Fix: Read agent_status and its output_tail for the reason.

Listed by agent_start, agent_message, agent_events, agent_status, agent_interrupt, agent_stop, agent_list, agent_sign_in, agent_add, agent_remove, agent_send, persistent_agent_save, agent_pause, agent_resume.

timeout#

A wait ran out: a claim that never bound, a Space that never became ready, or a command past its timeout.

Fix: Retry, or raise the tool's timeout.

Listed by create_space, resize_space, start_space, space_bash.

cancelled#

The create was cancelled (cancel_create, or its caller went away); what it made is gone.

Fix: Nothing to clean up; create it again when you want it.

stream#

The media plane failed to open or run the stream.

Fix: Check that the Space's spacesd supports desktop_stream or window_stream, then retry.

Listed by stream_endpoint, stream_space_window.

env#

A cua-spacesd call failed.

Fix: Retry; if it persists, check the spacesd log in the Space.

invalid_placement#

The location, kind or runtime does not exist, or the combination (with the image) does not.

Fix: Use one of the values the message lists, or leave kind and runtime unset (auto).

Listed by create_space.

sandbox#

Starting, stopping or deleting the Space's sandbox failed.

Fix: Check the local runtime (cua doctor) or the cloud pool, then retry.

Listed by create_space, network_log, network_set, delete_space, stop_space, resize_space, start_space, agent_pause, agent_resume.

cloud#

Your cloud account refused or failed a call Cua made for a Space there (AWS, Google Cloud, Hetzner, Modal): a missing permission, a quota, a region without the instance type. The message names the cloud's own error.

Fix: Fix what the message names in that account (cua cloud test <provider> checks without creating anything), or connect another region or project.

Listed by stop_space, start_space, cloud_connect, cloud_test, cloud_disconnect, cloud_approve, cloud_sweep, cloud_plan, cloud_hosts, cloud_add_host, cloud_remove_host, cloud_reconcile, prewarm, prewarm_list, prewarm_remove.

relay#

The cua.ai relay directory failed.

Fix: Retry; check cua auth status.

Listed by list_spaces, stop_space, start_space, share_space, unshare_space, space_shares, relay_register_space, relay_unregister_space.

mcp#

An MCP service inside the Space failed.

Fix: Check the service with list_tools; the message carries its error.

Listed by list_tools, call_tool.

io#

Reading or writing a local file failed.

Fix: Check the path and its permissions on this computer.

Listed by upload, send_file, download.

json#

A reply could not be parsed.

Fix: Retry; report it if it persists.

forbidden#

The drive's access rules refuse this principal on this path (an agent outside its own home, its Space's folder, read-only public/ and its grants).

Fix: Ask for access with volume_request_access; the user approves it in Cua.

Listed by thread_post, thread_reply, volume_ls, volume_read, volume_write, volume_delete, volume_history, volume_restore, volume_grant, volume_revoke, volume_grants, volume_request_access, volume_requests, volume_approve, volume_deny, volume_audit, volume_storage, volume_storage_set, volume_mount_status, volume_mount, volume_unmount, volume_sync_status, volume_sync_events, volume_sync_resolve, volume_cache_stats, volume_cache_set, volume_cache_clear.

precondition_failed#

A drive write or delete with if_etag or create_only found a different version at the path.

Fix: Read the file again and retry with its current etag.

Listed by volume_write, volume_delete.

secret_detected#

A write under agents/ carries something that looks like a secret (an API key, a token, a private key); it was not stored. The message names the kind and line, never the value.

Fix: Remove the secret from the file; keep credentials in the Keyvault.

Listed by persistent_agent_save, volume_write, volume_restore.

lease_held#

Another run holds the persistent agent's home (one writer at a time).

Fix: Wait for that run to stop, or stop it; the lease expires on its own.

Listed by agent_send.

not_signed_in#

Redeeming a join code needs the redeemer's Cua sign-in, and this computer is not signed in.

Fix: Sign in (cua auth login), then redeem the code again.

Listed by thread_join_redeem.

join_code_refused#

The join code was used, cancelled or has expired, or it is for a Space on another computer. The daemon never says which.

Fix: Ask for a new link in Add an agent.

Listed by thread_join_redeem.

rate_limited#

Too many wrong join codes from this account, or too many posts from this agent (30 a minute, 600 an hour).

Fix: Wait the time the message gives, then try again.

Listed by thread_join_redeem.

task_claimed#

Another session of the agent (or a newer drive of the same session) holds the task's claim; the message names the holder (<member>/<session>@<epoch>).

Fix: Leave the task to its holder; it is queued again on its own if the holder's lease runs out.

Listed by thread_claim.

not_confirmed#

The user did not confirm with presence (Touch ID, the login password or the vault passphrase), so no access was widened.

Fix: Ask the user to approve it in Cua.

Listed by computer_access_grant, volume_grant, volume_approve.

volume_backend#

The drive's store failed or is not configured (a bucket that refused, missing keys, or a backend this build cannot serve).

Fix: Check cua volume config show and the message.

Listed by volume_ls, volume_read, volume_write, volume_delete, volume_history, volume_restore, volume_unmount.

Protocol errors#

JSON-RPC errors are about the message, not the tool.