Snapshots

Turn a prepared conversation workspace into an immutable runtime you can reuse for new agents.

Overview

A snapshot is an immutable copy of a conversation workspace at an exact turn. Use it after an agent has installed tools or prepared files that future coworkers should start with. Snapshot creation runs asynchronously and does not block later conversation turns.

AgentContainer always removes the harness conversation context at /workspace/.agentcontainer/pi-sessions. The rest of the workspace is preserved.

Create a snapshot

Create snapshots from conversation tasks. If a turn is running, the request binds to that exact turn and waits for its checkpoint. If the conversation is awaiting input or hibernating, it immediately uses the latest completed turn. An idempotency key safely retries the same request.

Create snapshotbash
curl -X POST "$AGENTCONTAINER_URL/api/v1/conversations/tsk_123/snapshots" \
  -H "Authorization: Bearer $AGENTCONTAINER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: prepare-coworker-v1" \
  -d \'{"name":"Prepared coworker","ttlSeconds":2592000}\'

The response is 202 Accepted. Poll GET /api/v1/snapshots/:snapshotId until its status is ready or failed. A request can move through pending_turn, processing, and ready. If ttlSeconds is omitted, the snapshot does not expire automatically; otherwise its TTL begins when it becomes ready.

Snapshot build time is charged at the same container-minute rate as task execution, and snapshot requests require an available compute balance.

Reuse a snapshot

Once ready, pass the snapshot ID anywhere an agent runtime container image is accepted. The ID starts with snp_. AgentContainer resolves it to the immutable image and pins that runtime for the agent version.

Use snapshot as an agent runtimebash
curl -X POST "$AGENTCONTAINER_URL/api/v1/agents" \
  -H "Authorization: Bearer $AGENTCONTAINER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"Prepared coworker",
    "runtime":{"containerImage":"snp_0123456789abcdef0123456789abcdef","agentRuntime":"pi"},
    "basePrompt":"Continue from the prepared workspace",
    "defaults":{
      "model":"sonnet",
      "internetAccess":true,
      "maxRuntimeSeconds":600,
      "outputPolicy":{"mode":"none"},
      "runtimeRegion":"any"
    }
  }'

Retention and deletion

Deleting a snapshot removes the reusable snp_ resource, but it does not break agent versions or active tasks that already reference the runtime. Managed runtime storage is released only after every reference is gone, and snapshots share the checkpoint storage quota.

To discard a pinned runtime from an old agent version, call POST /api/v1/agents/:agentId/versions/:versionId/release-runtime. This is irreversible: the version metadata remains, but the version can no longer run. You cannot release the current version of an active agent or a version used by a nonterminal task. After archiving an agent, its current version can be released too.