Session workspace and state

Each session has its own workspace directory. Runs in the session read and write it; a new session starts clean. Files you attach land there, and the agent’s harness state lives there too. Nothing in the workspace is shared across tenants, and nothing is baked into the version.

At a glance

• The workspace is /workspace, mounted per session over durable tenant-scoped storage.
• State persists across runs in a session, and across suspend and resume. A new session starts empty.
• session.idle_timeout and session.max_lifetime bound how long a session lives.
• Warm starts restore the harness process, not your data: the golden snapshot contains no tenant state.

What lives in the workspace

Content	Written by	Persists
Files you attach with the Files API	Your application	For the session
Files the agent writes	The agent	For the session
Harness state: conversation continuity, tool results	The harness	For the session, across runs and suspend/resume
A project CLAUDE.md, when enable_claude_md is on	You, in the bundle	Read as a context file
Agent skills at .claude/skills/, when your agent ships a skills/ directory	The platform, from your image	Rebuilt from the image each run

The workspace belongs to one session. A later run continues it; a fork or another session does not see it. Files are first-class resources with their own ids and integrity checks, so an upload is never a blind write; see Attach files to a session.

Declare persistence and limits

agent.yaml

persistent: true
session:
  idle_timeout: 30m
  max_lifetime: 24h

• persistent: true provisions durable tenant-scoped storage and gives each session its own directory. It is required for new hosted versions.
• idle_timeout is how long a session may sit with no run before it is expired.
• max_lifetime is the longest a session may exist, idle or not.

Both are compact durations that resolve to whole seconds: 45s, 30m, 24h. An expired session can be resumed explicitly; see Sessions and runs.

Idle is cheap

An idle session is suspended: its harness process is checkpointed and the worker released, and it is restored in well under a second when the next run arrives. The workspace stays where it is. Your application does not see the difference; the session status stays idle either way, and you never call resume for it.

What is not state

• The version’s contract is immutable and lives in the registry, not the workspace.
• Credentials are never in the workspace. Connector credentials are held by the platform and presented at the gateway; see Secrets and configuration.
• Evidence is recorded outside the session: the audit trail and the execution trace survive the session’s expiry.

Where to go next

• Attach files to a session
• Agents and versions: warm starts and snapshots.
• Agent manifest: the fields.