Reference
Every Spaces tool by category, with parameters, results, errors and approval.
Every Spaces tool by category, with parameters, results, errors and approval.
The Spaces contract: 86 tools with the same names and schemas on every surface: cua mcp, cua daemon mcp and the Spaces SDKs. Contract 0.7.0, MCP protocol revision 2025-06-18, transports mcp_stdio and mcp_streamable_http. Experimental: names and shapes can change between minor versions.
Register, provision, list and release Spaces.
| Tool | Description | Effect |
|---|---|---|
add_space | Add an existing machine as a Space by address and token. | mutating, idempotent |
remove_space | Forget a registered Space without touching it. | mutating, idempotent |
list_spaces | List the Spaces this connection can see. | read-only, idempotent |
create_space | Create a Space: a new sandbox on this machine, on one of your machines, or in the cloud. | destructive |
delete_space | Delete a Space's sandbox and forget it. | destructive |
stop_space | Turn a Space off: suspend it (memory kept) or stop it (disk kept). | mutating, idempotent |
start_space | Turn a Space back on: resume or boot it. | mutating, idempotent |
Run shell commands and move files in and out of a Space.
| Tool | Description | Effect |
|---|---|---|
space_bash | Run a shell command inside the Space. | destructive |
space_write | Write literal text to a path inside the Space. | destructive |
upload | Send a local file or folder into the Space. | destructive |
send_file | Send a host file or folder into the Space's Downloads, verified by sha256 on arrival. | destructive |
download | Fetch a file or folder out of the Space. | read-only, idempotent |
Stream a Space's desktop or windows, and show a Space to the operator.
| Tool | Description | Effect |
|---|---|---|
stream_endpoint | Return a ticketed media endpoint for the Space's desktop or one window. | mutating, idempotent |
list_space_windows | List the windows open inside the Space. | read-only, idempotent |
stream_space_window | Draw one Space window on the operator's desktop. | mutating, idempotent |
show_space_pip | Pin the Space as picture-in-picture on the operator's desktop. | mutating, idempotent |
hide_space_pip | Unpin the picture-in-picture window. | mutating, idempotent |
open_space_viewer | Open the full Space viewer on the operator's desktop. | mutating, idempotent |
Discover and call the MCP services inside a Space.
| Tool | Description | Effect |
|---|---|---|
list_tools | List the MCP services and tools reachable inside the Space. | read-only, idempotent |
call_tool | Call a service tool inside the Space. | destructive |
Run coding agents inside a Space.
| Tool | Description | Effect |
|---|---|---|
agent_start | Start a coding agent in the Space. | destructive |
agent_message | Send a follow-up to an agent run. | destructive |
agent_events | Read an agent run's events after a cursor. | read-only, idempotent |
agent_status | Read an agent run's status and result. | read-only, idempotent |
agent_interrupt | Interrupt an agent run's current turn. | destructive |
agent_stop | Stop an agent run. | destructive |
agent_list | List agent runs in the Space. | read-only, idempotent |
agent_capabilities | Report what the agent harnesses support. | read-only, idempotent |
Named agents whose memory outlives their Space: homes in Cua Volume, routines, notifications, pause and resume, access to the user's computers.
| Tool | Description | Effect |
|---|---|---|
persistent_agent_create | Create a named agent whose memory outlives its Space. | destructive |
persistent_agent_list | List persistent agents. | read-only, idempotent |
persistent_agent_remove | Forget a persistent agent. | destructive |
persistent_agent_send | Give a persistent agent a turn. | destructive |
persistent_agent_save | Save a persistent agent's home now. | mutating, idempotent |
agent_pause | Pause a persistent agent: its run, its routines and its Space. | mutating, idempotent |
agent_resume | Resume a paused persistent agent. | destructive |
routine_add | Schedule a recurring turn for a persistent agent. | destructive |
routine_list | List routines. | read-only, idempotent |
routine_remove | Delete a routine. | mutating, idempotent |
routine_set_enabled | Turn a routine on or off. | mutating, idempotent |
notify_user | Tell the user something in the Cua app. | destructive |
notifications_list | Read the notifications feed. | read-only, idempotent |
notifications_ack | Mark notifications read. | mutating, idempotent |
computer_access_grant | Let a persistent agent use one of the user's computers. | destructive |
computer_access_revoke | Take back a persistent agent's access to a computer. | mutating, idempotent |
computer_access_list | List per-agent computer access. | read-only, idempotent |
Move a signed-in app session from this machine into a Space.
| Tool | Description | Effect |
|---|---|---|
teleport_manifest | Describe what a session teleport would move. | read-only, idempotent |
teleport_app | Move an app session into the Space. | destructive |
Use the user's saved credentials in a Space, only with their approval.
| Tool | Description | Effect |
|---|---|---|
request_site_login | Sign in to a site in the Space with the user's saved password. | destructive |
Share this machine's network with a Space.
| Tool | Description | Effect |
|---|---|---|
hotspot_start | Start sharing this machine's network with a Space. | destructive |
hotspot_stop | Stop sharing this machine's network. | destructive |
hotspot_status | Report which Spaces are sharing this machine's network, with counters. | read-only, idempotent |
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.
| Tool | Description | Effect |
|---|---|---|
volume_ls | List a folder of the Cua Volume. | read-only, idempotent |
volume_read | Read a file from the Cua Volume. | read-only, idempotent |
volume_write | Write a file to the Cua Volume. | destructive |
volume_delete | Delete a file from the Cua Volume. | destructive |
volume_history | List a Cua Volume file's versions. | read-only, idempotent |
volume_restore | Restore an old version of a Cua Volume file. | destructive |
volume_grant | Grant an agent or Space more Cua Volume access. | destructive |
volume_revoke | Revoke a Cua Volume grant. | mutating, idempotent |
volume_grants | List Cua Volume grants. | read-only, idempotent |
volume_request_access | Ask the user for more Cua Volume access. | destructive |
volume_requests | List Cua Volume access requests waiting for the user. | read-only, idempotent |
volume_approve | Approve a Cua Volume access request. | destructive |
volume_deny | Decline a Cua Volume access request. | destructive |
volume_audit | Read the Cua Volume audit log. | read-only, idempotent |
volume_storage | Show where the Cua Volume keeps its bytes. | read-only, idempotent |
volume_storage_set | Test or change where the Cua Volume keeps its bytes. | mutating, idempotent |
volume_mount_status | Show whether the Cua Volume is mounted as a volume. | read-only, idempotent |
volume_mount | Mount the Cua Volume as a volume. | mutating, idempotent |
volume_unmount | Unmount the Cua Volume volume. | mutating, idempotent |
volume_sync_status | Show the Cua Volume's sync state across devices. | read-only, idempotent |
volume_sync_events | Wait for Cua Volume sync events. | read-only, idempotent |
volume_sync_resolve | Mark a Cua Volume sync conflict as seen. | mutating, idempotent |
volume_cache_stats | Show the Cua Volume block cache. | read-only, idempotent |
volume_cache_set | Set the Cua Volume block cache's size cap. | mutating, idempotent |
volume_cache_clear | Clear the Cua Volume block cache. | mutating, idempotent |
Let other cua.ai accounts watch or edit a Space, through the relay.
| Tool | Description | Effect |
|---|---|---|
share_space | Let another cua.ai account watch or edit a Space. | mutating, idempotent |
unshare_space | Stop sharing a Space with an account, or with everyone. | mutating, idempotent |
space_shares | List who a Space is shared with. | read-only, idempotent |
relay_register_space | Publish a Space on the relay for the account's other devices. | mutating, idempotent |
relay_unregister_space | Take a Space off the relay. | mutating, idempotent |
Create Spaces in your own AWS, Google Cloud or Modal account: connect it, check it, and clean up what Cua created there.
| Tool | Description | Effect |
|---|---|---|
cloud_status | List your clouds (AWS, Google Cloud, Modal): found credentials, the connected account and region, what each can run at what hourly cost, and what Cua created there. | read-only, idempotent |
cloud_connect | Connect a cloud account Spaces can be created in. | mutating, idempotent |
cloud_test | Check a cloud account without creating anything. | read-only, idempotent |
cloud_disconnect | Forget a connected cloud account. | mutating, idempotent |
cloud_sweep | Find and delete what Cua left in your clouds. | destructive |
Every tool that takes space accepts a Space id or its name.
| Provider | Id | Tools |
|---|---|---|
cloud | cloud:<name> | all but the provider-only ones |
local | local:<name> | all but the provider-only ones |
direct | direct:<host:port> | all but the provider-only ones |
relay | relay:<machine-id> | all but the provider-only ones |
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.readOnlyHint, destructiveHint, idempotentHint, openWorldHint); clients use them to decide what to confirm. The Approval row of each tool shows them.acknowledge_sensitive for sensitive items.A failed call returns a tool result with isError: true and a machine kind. See Errors.