# Session workspace and state

What the agent can write to, what persists across runs and sessions, and how idle and lifetime limits shape a session.

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.

- 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](/guides/build/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](/guides/run/attach-files).

## Declare persistence and limits

```yaml title="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](/concepts/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](/guides/build/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](/guides/run/attach-files)
- [Agents and versions](/concepts/agents-and-versions): warm starts and snapshots.
- [Agent manifest](/reference/agent-manifest#state-warm-starts-and-sessions): the fields.