Sharing and cloud tools

Share a Space with other accounts, and create Spaces in your own cloud: the tools with their parameters, results and errors.

Sharing#

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

share_space#

Let someone in your team watch or edit a Space.

Shares the Space through the cua.ai relay with one person in your own team, by verified email or account id, or with the whole team as team:<id> (as a viewer or an editor). Sharing is for teams: an account in no team gets sharing_needs_team ("Sharing is for teams. Start a team to share this Space."), and someone outside your team gets share_outside_team. The same allowlist and device enrollment cua host share uses. A viewer joins presence with their own named cursor and watches a view-only stream: the Space's driver refuses their input, shell, files and MCP. An editor gets full use, and their input is a human session. Sharing again changes the role. A host (relay:<id>) is shared directly; any other Space (local, cloud, or added by address) is attached to the relay on its first share: its own driver dials out, so it needs no inbound port. Invitees open invitee_space.

Parameters#

Result#

JSON: space, machine (the relay computer it is shared as; empty when not shared), invitee_space (what the people it is shared with open: relay:<computer>), url, online and shares (each who, role: viewer or editor, and connected).

Errors#

invalid_argument, not_found, ambiguous_sandbox, host_capability_missing, relay, permission_denied, unauthenticated

Notes#

• Viewers and editors are enforced by the Space's own cua-spacesd, not by the caller; a Space whose driver predates relay_attach reports capability_missing.

unshare_space#

Stop sharing a Space with an account, or with everyone.

Removes one account (or everyone) at once: the relay cuts their open streams and refuses new calls. With no who, the Space stops being shared and a Space that is not a host leaves the relay.

Parameters#

Result#

JSON: space, machine (the relay computer it is shared as; empty when not shared), invitee_space (what the people it is shared with open: relay:<computer>), url, online and shares (each who, role: viewer or editor, and connected).

Errors#

invalid_argument, not_found, ambiguous_sandbox, host_capability_missing, relay, permission_denied, unauthenticated

space_shares#

List who a Space is shared with.

Who the Space is shared with, in which role, and who of them is connected through the relay now.

Parameters#

Result#

JSON: the shares (see share_space) and, with audit, audit: the newest owner-side lines (ts_ms, action: share, unshare, attach or detach, space, detail).

Errors#

invalid_argument, not_found, ambiguous_sandbox, host_capability_missing, relay, unauthenticated

relay_register_space#

Publish a Space on the relay for the account's other devices.

Publishes the Space as a computer of the signed-in account on the cua.ai relay, the way cua host setup publishes this computer: the Space's own driver joins the relay over outbound WSS with a computer token the account registered, so no inbound port is opened. The account's other devices (a phone off this network, the Cua app on another computer) then open relay_space; nobody else can until share_space adds them. Idempotent, and it re-attaches a Space that restarted. Needs a driver with relay_attach (a host is already registered).

Parameters#

Result#

JSON: space, relay_space (relay:<computer>: how the account's other devices reach it), machine, url and online.

Errors#

invalid_argument, not_found, ambiguous_sandbox, host_capability_missing, relay, unauthenticated

relay_unregister_space#

Take a Space off the relay.

Takes the Space off the relay: its driver leaves and its computer is removed, with every share. A relay:<computer> id removes that computer's record from the relay directory, which only its owner may do: a Space that registered itself (also after it was deleted), or a computer that is no longer connected. A host that is connected now is taken off with cua host remove on that computer instead.

Parameters#

Result#

JSON: space and unregistered (false when it was not on the relay).

Errors#

invalid_argument, not_found, ambiguous_sandbox, host_capability_missing, relay, unauthenticated, permission_denied

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.

cloud_status#

List your clouds (AWS, Google Cloud, Hetzner, Modal): found credentials, the connected account and region, what each can run at what hourly cost, and what Cua created there.

Sandboxes and Spaces can run in the user's own cloud account: on="aws" (EC2), "azure" (Azure Virtual Machines), "gcp" (Compute Engine), "hetzner" (Hetzner Cloud) or "modal" (Modal Sandboxes). EC2, Azure, Compute Engine and Hetzner Cloud start one small VM or server per sandbox that runs the image with Docker; Modal runs one Modal sandbox. Hetzner Cloud servers have no /dev/kvm, so Hetzner runs container images only (Windows and other VM images are refused). Either way the guest's cua-spacesd dials out to the cua.ai relay as a computer of the signed-in account (no inbound port), and the Space is that computer, relay:<computer>. AWS and Google Cloud use their own CLI sign-in or, with auth="oidc", no stored key at all (Cua's issuer signs short-lived tokens the account trusts); Azure always links that way; Modal uses its CLI sign-in; Hetzner uses a project API token (Read & Write), and Modal can take its token too: cloud_connect seals it to the account's devices (Cua's servers keep only ciphertext; no tool returns it), or keeps Hetzner's in this device's Cua credential store (auth="cli"). Connect it first with cloud_connect (the user decides; it costs money in their account). Everything Cua creates is tagged cua-managed=true with this cua home's cua-owner and an expiry, recorded under the cua home, deleted with its sandbox, and ends itself at its expiry (a Hetzner server, which cannot delete itself, shuts down and is billed until cloud_sweep or delete_space removes it); cloud_sweep removes leftovers, and the daemon runs that sweep by itself every 15 minutes (CUA_CLOUD_SWEEP_SECS; 0 turns it off). cloud_disconnect refuses while Cua resources still run there unless delete=true; cloud_audit lists what Cua did.

Parameters#

Result#

JSON: default_on, providers (each name, title, tier (vm: a VM that provides Spaces, sandbox: one sandbox per Space), connected, default, credentials (found, source), account, profile, region, zone, project, environment, label ("AWS · us-west-2"), ttl_hours, kinds (each image, kind, supported, reason, machine_type, usd_per_hour), auth (cli, oidc or sealed once connected), status (connected, waiting-for-approval, not-connected, or failed when the link was revoked), budget_usd_month and max_size when set, spent_month (estimated US dollars this calendar month), running (machines Cua runs there now), approval (connection or limits while a person's approval is pending, else absent) and, for sealed, holders (the devices that can open the API token now; at least one must be online for machines to be made there unattended)) and resources (what Cua created: provider, id, type, space, region, state, created, expires, expired).

Errors#

invalid_argument

cloud_connect#

Connect a cloud account Spaces can be created in.

Without auth it keeps how the cloud is linked already (an OIDC or sealed link stays so, so a run that only changes budget_usd_month or max_size never falls back to a CLI sign-in); a cloud not linked yet, or auth="cli", runs cloud_test first and connects only when every check passes, storing the profile, region, project or environment names under the cua home (never a key: the cloud's own CLI sign-in stays where it is). auth="oidc" links AWS, Google Cloud or Azure with no stored key (Azure is always oidc; a Google Cloud project_number implies it): it never prompts and is idempotent, so call it again with the same arguments until status is connected, following next each time. It needs budget_usd_month first. Until the account is named it returns needs-trust and the trust step: a page for the person (AWS: the trust stack, then ask for the 12-digit account_id; Google Cloud: Cloud Shell and the trust script, then ask for the project_number it prints; Azure: Deploy to Azure, then ask for the outputs subscription_id, tenant_id and client_id), or, when an agent asks on a machine signed in to gcloud or az, the exact command to run. Once named, the link is recorded on Cua's issuer and check=true proves it (a check token, the exchange with the cloud, a dry run, permission check or validate; nothing is created) and saves it. Hetzner and Modal with a token and budget_usd_month seal the token to the account's devices (auth="sealed", the default on a device with the account's pool keys): it is checked first (nothing is created), Cua's servers keep only ciphertext, any device of the account opens it in memory when it calls the cloud, and no tool ever returns it; on another device, auth="sealed" without a token links the account's sealed token. A link, token or limit raise made by an agent returns waiting-for-approval until a person approves it in Cua Spaces. budget_usd_month and max_size (4x16) also apply to CLI links: machines past them are refused before any cloud call. With make_default, create_space without on creates there (default.on).

Parameters#

Result#

JSON: the cloud as cloud_status lists it, whose status is the outcome (connected, needs-trust, checking, waiting-for-approval or failed), plus checks (each name, ok, detail), next (absent when connected; run: the exact command for the agent, or open: a page for a person, with paste when there is a command to paste there, and why) and verify (the command that confirms it).

Errors#

invalid_argument, cloud

cloud_test#

Check a cloud account without creating anything.

Creates nothing: it signs in with the cloud's own CLI credentials (or, for a link without a stored key, a token from Cua's issuer exchanged with the cloud), asks the cloud to validate a create without doing it (AWS DryRun, Google Cloud permission checks, an Azure deployment validate), and reads quotas. A failed check says what to fix.

Parameters#

Result#

JSON: provider, ok, account (the account, project or workspace the credentials reach) and checks (each name, ok, detail: credentials, permissions by dry run, quota, the region and machine types).

Errors#

invalid_argument, cloud

cloud_disconnect#

Forget a connected cloud account (deleting what Cua created there first, with delete=true).

Refuses (a cloud error listing them) while Cua-created instances or sandboxes still run in that cloud, because a disconnected cloud is no longer swept and they would bill unseen. With delete=true it first deletes everything Cua created there (the same tag and record checks as cloud_sweep with all=true), then asks the cloud again and forgets the connection (and default.on when it named this cloud) only when nothing is left; if something remains it keeps the connection and says what. Nothing that Cua did not create is ever touched.

Parameters#

Result#

JSON: provider, disconnected, deleted (with delete=true: the receipt, each resource deleted first) and left (resources Cua still records there).

Errors#

invalid_argument, cloud

cloud_approve#

Approve (or deny) what an agent asked for on a cloud: its link or its raised limits. For a person only.

Only for a person, never for an agent: no MCP server lists or runs it, the daemon refuses it when it runs for an agent, and Cua's issuer refuses an agent's proof. It approves what an agent asked for on that cloud (its link, or a raise of its budget or largest machine; see approval, approval_agent, pending_budget_usd_month and pending_max_size in cloud_status), or with deny=true declines it: a raise is dropped and the limits in force stay; a link never approved is disconnected.

Parameters#

Result#

JSON: the cloud as cloud_status lists it once approved or denied (status, approval empty, the limits in force).

Errors#

invalid_argument, cloud

cloud_sweep#

Find and delete what Cua left in your clouds.

Acts only on resources that carry Cua's tags (cua-managed=true and this device's cua-owner) and that this cua home recorded, or that carry this device's owner id: never on anything else in the account. Default dry_run=true lists what it would delete: expired Spaces (past their ttl), resources whose Space is gone, and with all=true every Cua resource there.

Parameters#

Result#

JSON: dry_run and resources, each provider, id, type, space, expires, action (delete, deleted, keep or failed) and reason.

Errors#

invalid_argument, cloud

cloud_plan#

Show (or apply) the elastic pool's plan for some Spaces: where they go, which machines it adds, and the cost.

The elastic pool places Spaces with on="auto" (or on a linked cloud) by one solve: the user's devices first (free), then cloud hosts already running, then new cloud hosts (provider x type x region) at the least cost that fits the image's needs (kind, KVM, arch, size learned from earlier Spaces), the start-time goal, the relay's machine limit and the budget (cloud_budget). Idle cloud hosts go at the end of their paid time. cloud_plan shows the decision without doing it; pins (provider, region, instance_type, hosts, no_scale, devices_only, max_usd_per_hour) are constraints of the same solve, so an agent can inspect, adjust and apply.

Parameters#

Result#

JSON: plan (assignments: group, target (on: host with name, or new with index), count; new_hosts: provider, type_name, region, usd_per_hour, boot_secs, billed_secs; unplaced with reason; added_usd_per_hour, projected_usd, lower_bound_usd, solver, ready_in_secs, explain), groups (the demand it detected) and pool (hosts, cloud, offers, constraints, month_usd); with apply, added (the hosts added).

Errors#

invalid_argument, cloud, limit_exceeded

cloud_hosts#

List the hosts the elastic pool added in your clouds.

The hosts the elastic pool (or cloud_add_host) added in the user's linked clouds: machines that provide Spaces to the pool, with their live cost.

Parameters#

No parameters.

Result#

JSON array: each host name, provider, type_name, region, id, machine, state (creating, booting, joined, cordoned, offline, gone), started, expires, usd_per_hour, billing_step_secs, billing_min_secs, pinned.

Errors#

invalid_argument, cloud

cloud_add_host#

Add hosts to your pool in a linked cloud.

Adds hosts by hand (pinned: the scaler never removes them); it costs money in the user's account. Each host is tagged and recorded first, installs cua, joins the pool and ends at its TTL. cloud_remove_host removes it.

Parameters#

Result#

JSON array: the hosts added (see cloud_hosts).

Errors#

invalid_argument, cloud

cloud_remove_host#

Remove hosts this home added to your pool.

Deletes the hosts' machines (only ones this cua home added and tagged) and their relay entries. The Spaces on them end.

Parameters#

Result#

JSON: removed (names) and failed (each name, error).

Errors#

invalid_argument, cloud, not_found

cloud_budget#

Read or set the elastic pool's budget and autoscale switch.

The caps the elastic pool keeps to: it never adds a machine that would take the clouds' cost over max_usd_per_hour or this month's spend over monthly_usd, and with autoscale false it adds none. Fields given are set; the rest stay.

Parameters#

Result#

JSON: policy (autoscale, max_usd_per_hour, monthly_usd, max_new_hosts, warm, interactive_slo_secs, routed, allow_metal), month_usd (spent this month on elastic hosts), running_usd_per_hour and hosts (how many run).

Errors#

invalid_argument

cloud_reconcile#

Run the elastic pool's scale-in pass now.

One scale-in pass now (the daemon runs one every 30 s): idle hosts go at the end of the time already paid, the least-used one is cordoned when the others have room.

Parameters#

No parameters.

Result#

JSON array: each host and action (action: keep with until and reason, cordon with reason, or remove with reason and saves_usd).

Errors#

invalid_argument, cloud

prewarm#

Keep Spaces of one shape ready where the elastic pool puts them, so the next creates start in a fraction of a second.

A prewarm keeps count Spaces of one shape (image, kind, cpus, memory_mb) ready on the machines the elastic pool picks (the same solve as on="auto": devices first, then hosts with room, then new cloud machines, under the budget and pins). Any later create of that shape on those machines claims one in a fraction of a second, through every surface, with no extra argument; the pool keeps count ready until ttl_secs. A prewarm the budget, quotas or pins cannot fit is refused and buys nothing. End it with prewarm_remove when the burst is over.

Parameters#

Result#

JSON: id, image, kind, cpus, memory_mb, count, ready, placements (host, machine, count, ready), expires_at (unix seconds) and new_hosts (hosts added for it).

Errors#

invalid_argument, limit_exceeded, cloud

prewarm_list#

List the prewarms and how many Spaces each keeps ready.

A prewarm keeps count Spaces of one shape (image, kind, cpus, memory_mb) ready on the machines the elastic pool picks (the same solve as on="auto": devices first, then hosts with room, then new cloud machines, under the budget and pins). Any later create of that shape on those machines claims one in a fraction of a second, through every surface, with no extra argument; the pool keeps count ready until ttl_secs. A prewarm the budget, quotas or pins cannot fit is refused and buys nothing. End it with prewarm_remove when the burst is over.

Parameters#

No parameters.

Result#

JSON array of prewarms, as prewarm returns them, with ready counted now.

Errors#

invalid_argument, cloud

prewarm_remove#

End a prewarm: its ready Spaces go.

A prewarm keeps count Spaces of one shape (image, kind, cpus, memory_mb) ready on the machines the elastic pool picks (the same solve as on="auto": devices first, then hosts with room, then new cloud machines, under the budget and pins). Any later create of that shape on those machines claims one in a fraction of a second, through every surface, with no extra argument; the pool keeps count ready until ttl_secs. A prewarm the budget, quotas or pins cannot fit is refused and buys nothing. End it with prewarm_remove when the burst is over.

Parameters#

Result#

JSON: removed (false when there was no such prewarm).

Errors#

invalid_argument, cloud

cloud_audit#

Read the log of what Cua did in your clouds.

Reads the append-only audit log under the cua home (cloud/audit.jsonl, rotated at 5 MB): every connect, disconnect, resource recorded before its create, created, confirmed and deleted (by you, by a sweep, by the automatic sweep, by disconnect with delete), and each budget alert (budget_alert). These entries have source device. For clouds linked to the account (OIDC or a sealed token) it adds what Cua's issuer recorded, with source account: tokens issued or refused, links made, approved, changed and revoked. It never holds a secret or a token. provider narrows it to one cloud. Default limit 50.

Parameters#

Result#

JSON array, oldest first, newest last: each ts (RFC 3339), action (connect, disconnect, resource_recorded, resource_created, resource_confirmed, resource_deleted), provider, kind, id, space, actor (user, sweep, auto-sweep, disconnect, rollback), outcome (ok, failed, refused) and detail.

Errors#

invalid_argument

cloud_cost#

Estimate what Cua's machines in your clouds cost, by Space, agent, day or cloud.

Estimates what the machines Cua created cost: each one's list price times how long it ran inside the window, from the machines still recorded and the usage log of the ones gone (cloud/usage.jsonl under the cua home). by=space, agent (who started it: an agent's name, user, or unknown for machines recorded before that was kept), day (UTC) or cloud. since defaults to the first of this month. It is an estimate: the cloud's own bill is the final word. Pool hosts count under pool hosts.

Parameters#

Result#

JSON: by, since (YYYY-MM-DD), until (RFC 3339), rows (each key: the Space, agent, day or cloud; usd: estimated US dollars; hours: machine hours; machines: how many ran), by day oldest first, otherwise costliest first, and total_usd.

Errors#

invalid_argument