An agent's state lives on local disk

Notes from Anthropic's "Hosting the Agent SDK". The Agent SDK spawns a claude CLI subprocess that owns a shell, a working directory, and session files on disk. So hosting an agent isn't like hosting a stateless API wrapper. Every running agent is a long-lived process tied to local state.

State lives on local disk

By default, three kinds of agent state live on the container's filesystem:

• Session transcripts — JSONL files under ~/.claude/projects/.
• CLAUDE.md memory files — ~/.claude/CLAUDE.md for the user, and the working directory for the project.
• Working-directory artifacts — whatever the agent writes into its working directory.

None of them survive a container restart, a scale-down, or a move to another node. A SessionStore can persist transcripts, but it only covers transcripts. Memory files and artifacts need their own storage, such as a mounted volume or an object-store sync.

Four session patterns

Session lifecycle comes down to how long a container lives compared with the sessions it serves:

• Ephemeral — one container per task, destroyed when the task finishes. Good for one-off jobs like a bug fix, invoice extraction, or a translation.
• Long-running — persistent containers, often running several SDK processes each. Good for agents that run all the time: an email triager, a Slack bot, a hosted site builder.
• Hybrid — ephemeral containers that load the session from a SessionStore on startup and write updates back. Good for sessions that go idle between check-ins. Here the store is required: without it, shutting down the container loses the transcript.
• Multi-agent container — several SDK subprocesses in one container, for agents that work closely together. Give each agent its own working directory so their files and CLAUDE.md don't leak into each other.

The takeaway for me: before I pick where an agent runs, I need to decide where its state lives. The session pattern follows from that.

To learn the vocabulary behind this (process, subprocess, cwd, sandbox-runtime, container, microVM) and see which layer stops which problem, try the interactive companion: Agent Isolation Layers.