Persistent agents
Named agents whose memory outlives their Space: homes in Cua Volume, routines, notifications, pause and resume, access to the user's computers.
Named agents whose memory outlives their Space: homes in Cua Volume, routines, notifications, pause and resume, access to the user's computers.
| Tool | Description |
|---|---|
persistent_agent_create | Create a named agent whose memory outlives its Space. |
persistent_agent_list | List persistent agents. |
persistent_agent_remove | Forget a persistent agent. |
persistent_agent_send | Give a persistent agent a turn. |
persistent_agent_save | Save a persistent agent's home now. |
agent_pause | Pause a persistent agent: its run, its routines and its Space. |
agent_resume | Resume a paused persistent agent. |
routine_add | Schedule a recurring turn for a persistent agent. |
routine_list | List routines. |
routine_remove | Delete a routine. |
routine_set_enabled | Turn a routine on or off. |
notify_user | Tell the user something in the Cua app. |
notifications_list | Read the notifications feed. |
notifications_ack | Mark notifications read. |
computer_access_grant | Let a persistent agent use one of the user's computers. |
computer_access_revoke | Take back a persistent agent's access to a computer. |
computer_access_list | List per-agent computer access. |
Create a named agent whose memory outlives its Space.
A persistent agent is a harness with a name, a Space and a home in the Cua Volume (agents/<name>/). Its harness keeps its memory in the home (Claude Code auto memory, Codex memories, Hermes MEMORY.md, the OpenClaw workspace), which is restored into the Space before each run and saved after each turn, so the agent remembers across runs, Space releases and machines. One run writes a home at a time. Start it with persistent_agent_send (or agent_start with home=<name>); the daemon notifies the user when a turn ends. Inside the Space the agent gets the cua bridge: notify_user, the drive, and the user's computers it was granted.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:persistent_agent_create; destructive |
| Swift SDK | spaces.persistentAgents.create(...) |
| Rust | Persistent::create |
| 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. |
env | map of string | {} | More environment for every run (not secrets; see env_from_host). |
env_from_host | string[] | [] | Provider key variables forwarded from this server's environment at every start, for example ["ANTHROPIC_API_KEY"]. Names only. |
model | string | none | Model id. |
name | string | required | The agent's name: 1-63 of a-z, 0-9, ., _, -. Its home is agents/<name>/ in the Cua Volume. |
space | string | required | The Space it works in (id or name). |
JSON: the agent record: name, harness, space, model, base_url, env_from_host, paused, space_state and created_ms.
invalid_argument, not_found, ambiguous_sandbox, agent
List persistent agents.
Every persistent agent of this machine's cua home, with its Space, its current run and when its home was last saved.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:persistent_agent_list, in spaces:readonly; read-only, idempotent |
| Swift SDK | spaces.persistentAgents.list() |
| Rust | Persistent::list |
No parameters.
JSON: {"agents"}, each with name, harness, space, paused, space_state, run_id, saved_ms and last_error.
Forget a persistent agent.
Stops its run, removes its routines and forgets it. Its home (agents/<name>/) stays in the Cua Volume; delete it there.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:persistent_agent_remove; destructive |
| Swift SDK | spaces.persistentAgents.remove(_:) |
| Rust | Persistent::remove |
| Parameter | Type | Default | Description |
|---|---|---|---|
name | string | required | The persistent agent's name. |
JSON: removed (the record). The home stays in the Cua Volume.
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.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:persistent_agent_send; destructive |
| Swift SDK | spaces.persistentAgents.send(_:_:) |
| Rust | Persistent::send |
| Parameter | Type | Default | Description |
|---|---|---|---|
name | string | required | The persistent agent's name. |
text | string | required | The message (the prompt of a new run, or a follow-up). |
JSON: run_id, started (a new run, with the home restored) and restored (files, bytes, millis).
invalid_argument, agent, lease_held
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.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:persistent_agent_save; mutating, idempotent |
| Swift SDK | spaces.persistentAgents.save(_:) |
| Rust | Persistent::save |
| Parameter | Type | Default | Description |
|---|---|---|---|
name | string | required | The persistent agent's name. |
JSON: files, bytes, unchanged, removed, blocked (files the secret scanner kept out) and millis.
invalid_argument, agent, secret_detected
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 (Fleet has no per-claim pause), 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 machines are never suspended.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:agent_pause; mutating, idempotent |
| Swift SDK | spaces.persistentAgents.pause(_:) |
| Rust | Persistent::pause |
| Parameter | Type | Default | Description |
|---|---|---|---|
name | string | required | The persistent agent's name. |
JSON: stopped_run, saved (the home save), space_state (suspended, released or running) and millis.
invalid_argument, agent, sandbox
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.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | cloud |
| Approval | permission spaces:agent_resume; destructive |
| Swift SDK | spaces.persistentAgents.resume(_:prompt:) |
| Rust | Persistent::resume |
| Parameter | Type | Default | Description |
|---|---|---|---|
name | string | required | The persistent agent's name. |
prompt | string | none | Start a run on this prompt once the agent is back. Default: none (the next message or routine starts one). |
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).
invalid_argument, agent, sandbox, fleet
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.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:routine_add; destructive |
| Swift SDK | spaces.persistentAgents.addRoutine(...) |
| Rust | Persistent::routine_add |
| Parameter | Type | Default | Description |
|---|---|---|---|
agent | string | required | The persistent agent that runs it. |
daily_at | string | none | Every day at HH:MM (local time). |
enabled | boolean | true | Default true. |
every_minutes | integer | none | Every N minutes. |
prompt | string | required | What the agent is asked each time. |
title | string | required | A short title (shown in the app and prefixed to the turn). |
weekly_on | string | none | Every week at <weekday> HH:MM (local time), for example mon 09:00. |
JSON: the routine: id, botID (the agent), title, prompt, schedule, isEnabled and createdAt.
List routines.
Routines with their next firing and what the last one did.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:routine_list, in spaces:readonly; read-only, idempotent |
| Swift SDK | spaces.persistentAgents.routines(agent:) |
| Rust | Persistent::routines |
| Parameter | Type | Default | Description |
|---|---|---|---|
agent | string | none | Only this persistent agent's routines. Default: all. |
JSON: {"routines"}, each with id, botID, title, prompt, schedule, label, isEnabled, lastFiredAt, lastRunID, lastOutcome and next_fire.
Delete a routine.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:routine_remove; mutating, idempotent |
| Swift SDK | spaces.persistentAgents.removeRoutine(_:) |
| Rust | Persistent::routine_remove |
| Parameter | Type | Default | Description |
|---|---|---|---|
id | string | required | The routine's id. |
JSON: removed (the id).
Turn a routine on or off.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:routine_set_enabled; mutating, idempotent |
| Swift SDK | spaces.persistentAgents.setRoutineEnabled(_:_:) |
| Rust | Persistent::routine_set_enabled |
| Parameter | Type | Default | Description |
|---|---|---|---|
enabled | boolean | required | On or off. |
id | string | required | The routine's id. |
JSON: the routine.
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.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:notify_user; destructive |
| Swift SDK | spaces.notifications.post(...) |
| Rust | notify::Feed::post |
| Parameter | Type | Default | Description |
|---|---|---|---|
agent | string | none | The persistent agent it is about, if any. |
body | string | none | The details. Default empty. |
title | string | required | One short line. |
JSON: notified and id.
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.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:notifications_list, in spaces:readonly; read-only, idempotent |
| Swift SDK | spaces.notifications.list(...) |
| Rust | notify::Feed::list |
| Parameter | Type | Default | Description |
|---|---|---|---|
since_ms | integer | none | Only ones newer than this (Unix ms). At least 0. |
unread_only | boolean | false | Only unread ones. Default false. |
JSON: {"notifications"}, newest first, each with id, at_ms, agent, kind (turn_ended, message, approval, error), title, body, run_id, space and read.
Mark notifications read.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:notifications_ack; mutating, idempotent |
| Swift SDK | spaces.notifications.markRead(_:) |
| Rust | notify::Feed::ack |
| Parameter | Type | Default | Description |
|---|---|---|---|
ids | string[] | [] | Ids to mark read. Default: every notification. |
JSON: marked (how many changed).
Let a persistent agent use one of the user's computers.
Lets one persistent agent use one of the user's machines (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.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:computer_access_grant; destructive |
| Swift SDK | spaces.persistentAgents.allowComputer(_:machine:) |
| Rust | access::Access::grant |
| Parameter | Type | Default | Description |
|---|---|---|---|
agent | string | required | The persistent agent. |
expires_in_secs | integer | none | End the grant after this many seconds. Default: until revoked. At least 0. |
machine | string | required | The machine (a Space id, usually relay:<machine-id> from cua host setup). |
JSON: the grant: id, agent, machine, created_ms, expires_ms.
invalid_argument, not_confirmed
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.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:computer_access_revoke; mutating, idempotent |
| Swift SDK | spaces.persistentAgents.revokeComputer(_:machine:) |
| Rust | access::Access::revoke |
| Parameter | Type | Default | Description |
|---|---|---|---|
agent | string | required | The persistent agent. |
machine | string | none | The machine. Default: every machine. |
JSON: revoked (how many grants).
List per-agent computer access.
Which agents may use which of the user's computers, and the audited record of grants, uses and refusals.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:computer_access_list, in spaces:readonly; read-only, idempotent |
| Swift SDK | spaces.persistentAgents.computerAccess(agent:) |
| Rust | access::Access::grants |
| Parameter | Type | Default | Description |
|---|---|---|---|
agent | string | none | Only this persistent agent's grants. Default: all. |
audit | integer | 0 | Include the audit log's newest entries (this many). Default 0. At least 0. |
JSON: {"grants"} (each id, agent, machine, created_ms, expires_ms, revoked) and, with audit, audit (newest first: ts_ms, principal, action, path (the machine), detail) plus audit_verified.