Agents

A workspace per agent

A cloud agent is Claude Code or Codex running in a persistent workspace. A project can have a main agent and several extra agents. Each agent can have a Claude session and a Codex session; opening a live session reattaches it. The Cloud agents guide covers launch, apps and project sync (CLI 0.13.2+).

GET /v1/agents, cloud.agents.list() (TypeScript SDK 0.18.0+), sf.agents.list() (Python 0.14.0+) and agents_list (MCP 0.12.0+) report sessions. A workspace detail view carries its agents array. Sessions have an app, state, state-change time, title and optional Remote Control URL.

States and workspace activity

The workspace's parking state is separate. A waiting session in a parked workspace appears as parked. An exited session stays done. Detached working agents keep going: the session belongs to the workspace, and closing a client does not end it.

A live working session keeps the workspace awake for its whole turn. Waiting and exited sessions hold it for the configured grace, then ordinary idle rules apply. Background commands, CPU/network activity, keepalive and other active tools can also keep it awake. Agent workspaces count toward the plan's workspaces working at once while working or starting.

Choose the idle grace

Grace keeps a waiting or exited agent awake briefly before normal idle handling. It never interrupts a working turn. Set it with the workspace's agent idle grace option (TypeScript SDK 0.18.0+, Python 0.14.0+, CLI 0.13.2+, MCP 0.12.0+). Agent settings lists the values and defaults.

New agents and forks

Every new cloud agent starts from its machine and project template. At the workspace API, like inherits the source's exact template version, sizes, secret bindings, text inputs, volumes and agent options on a fresh disk (TypeScript SDK 0.18.0+, Python 0.14.0+, CLI 0.13.2+, MCP 0.12.0+). Explicit options override inherited ones. Reopening an existing key keeps its disk and template.

A cloud-agent fork copies the whole running state: files, memory, processes and services, with its machine and project template. It has its own agent conversation. Both keep shared-volume attachments, and neither copies the volume's contents. Shared volumes store data outside workspace snapshots; attached agents can read or write them according to the mount mode.

Machine and project templates are private filesystem templates and include secrets as ordinary files. Save or roll back either environment; files update live and software at the next start.

Keep and recover work

Extra-agent Git work is fetched into hidden refs/shard/<agent> refs (CLI 0.13.2+). Opening a local editor creates .shard/worktrees/<agent>. Merge applies committed work to the current branch, keep creates a real shard/<agent> branch, and discard deletes the agent's worktree, ref and workspace.

CLI housekeeping archives saved Git work as refs/shard/archive/<agent>. shard agents restore <agent> --path . returns that saved commit as a local branch. Retention settings describe its lifetime.

Stay reachable while waiting

Waiting Claude agents keep their Remote Control conversation reachable from claude.ai and the Claude mobile app for 30 minutes by default. A reply on the agent's connection wakes its parked workspace (CLI 0.13.2+, TypeScript SDK 0.18.0+, Python 0.14.0+, MCP 0.12.0+). The session title starts with [SF] .

The reachability window is separate from the idle grace: grace controls when waiting work can park, and agent_reachable_seconds controls how long a parked waiting agent can wake on reply traffic. See reachability settings and billing.