#Sessions

A session is the durable unit of agent work. It binds one agent snapshot, one environment, optional resources, and one or more vaults.

Official reference: Claude Managed Agents sessions.

Sessions can be created directly by application code or indirectly by a deployment run. After a deployment starts a session, read and control that session with the same session and event APIs used for direct sessions.

Create A Session#

typescript
const session = await client.beta.sessions.create({
    agent: agent.id,
    environment_id: environment.id,
    title: "Triage failing tests",
    vault_ids: [llmVault.id],
    resources: [{
        type: "github_repository",
        url: "https://github.com/anthropics/anthropic-sdk-typescript",
        checkout: { type: "branch", name: "main" },
    }],
    metadata: {
        workflow: "test-triage",
    },
});

Agent Snapshot#

The agent field can reference the latest agent:

typescript
const session = await client.beta.sessions.create({
    agent: agent.id,
    environment_id: environment.id,
    vault_ids: [llmVault.id],
});

It can also pin a specific version:

typescript
const session = await client.beta.sessions.create({
    agent: {
        type: "agent",
        id: agent.id,
        version: 1,
    },
    environment_id: environment.id,
    vault_ids: [llmVault.id],
});

Resources#

Resources are materialized into the session workspace.

File resources are created from Files API uploads. When an uploaded file is attached to a session, Sandbox0 creates a new session-scoped file id for the resource. Use files.list with scope_id: session.id to list those scoped files and any output files captured for the session.

See Files for upload, scoped copy, output file, and limit details.

Repository authorization tokens are accepted on create or update, but are not returned in responses.

Lifecycle#

Sandbox0 keeps session state and event history outside the sandbox. The sandbox and workspace volume are runtime attachments for the session.

rescheduling is transient. It is emitted as session.status_rescheduled after a session.error whose error.retry_status.type is retrying. When the same run resumes and produces more output, Sandbox0 emits session.status_running again. If the retry budget is exhausted, the run returns to idle with stop_reason.type = "retries_exhausted"; terminal non-retryable failures move the session to terminated.

Sandbox0 Runtime Behavior#

• Agent harnesses create or resume a sandbox before the run starts.
• The workspace is backed by a Sandbox0 volume mounted at /workspace.
• The runtime sandbox uses auto-resume.
• Runtime sandbox lifetime is managed by the Managed Agents deployment.
• The selected agent harness is resolved from the attached LLM vault; if no harness is selected, the default is claude.
• claude and codex run the agent process inside the sandbox.
• Harnesses with observable automatic retry attempts map them to the same session state sequence: running, rescheduling, running, then either idle or terminated.

Next Steps#