# 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](https://platform.claude.com/docs/en/managed-agents/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.

| Resource | Purpose |
|----------|---------|
| `file` | Mount an uploaded file into the workspace |
| `github_repository` | Clone a repository into the workspace |

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

## Lifecycle

| State | Meaning |
|-------|---------|
| `idle` | Ready for new input or waiting for required action |
| `running` | The agent harness is processing events |
| `rescheduling` | The active run hit a retriable model or transport error and Sandbox0 is waiting for the selected harness to retry automatically |
| `terminated` | The session is no longer active |

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

- Creating or resuming work ensures a sandbox exists for the session.
- 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.
- `openai-agents` runs the agent loop in a resident runtime and uses Sandbox0 as a sandbox tool.
- All supported harnesses map observable automatic retry attempts to the same session state sequence: `running`, `rescheduling`, `running`, then either `idle` or `terminated`.

## Next Steps

<CardGroup>
  <Card title="Events" href="/docs/managed-agents/events" cta="Continue">
    Append user input, stream agent output, and interpret retry lifecycle events.
  </Card>

  <Card title="Vaults" href="/docs/managed-agents/vaults" cta="Continue">
    Store model and external service credentials outside agent code.
  </Card>
</CardGroup>
