# Compatibility

Sandbox0 Managed Agents follows the Claude Managed Agents API shape where practical, while using Sandbox0 as the execution backend.

Official reference: [Claude Managed Agents quickstart](https://platform.claude.com/docs/en/managed-agents/quickstart).

## Supported Surface

| Area | Status |
|------|--------|
| Official Anthropic SDK | Supported by setting `baseURL` to the Sandbox0 Managed Agents API endpoint |
| Managed Agents beta header | Required for direct HTTP calls. SDKs set it automatically. |
| Agents | Supported, including versioned agent definitions |
| Environments | Supported for `type: cloud` with package and networking configuration |
| Sessions | Supported with durable status, metadata, agent snapshot, resources, vault ids, usage, and stats |
| Events | Supported for list, send, and event streaming |
| Files | Supported for upload, metadata, download, delete, and file-backed message content |
| Vaults and credentials | Supported for LLM credentials, MCP credentials, and Sandbox0 HTTP header credential projection |
| Custom skills | Supported through uploaded skill versions |
| MCP servers | Supported for URL MCP servers and vault-backed credentials |
| GitHub repository resources | Supported at session creation |
| Agent harnesses | Supported for `claude`, `codex`, and `openai-agents` |
| External AI gateways | Supported when the gateway exposes the API shape required by the selected agent harness |

## Current Differences

| Difference | Sandbox0 behavior |
|------------|-------------------|
| SDK ownership | Sandbox0 does not ship a Managed Agents SDK. Use the official Anthropic SDK. |
| API token | SDK `apiKey` is a Sandbox0 API key, not the Anthropic LLM token. |
| LLM token | Stored in an LLM vault and projected by Sandbox0 credential policy. |
| Agent harness | Selected by the compatibility key `sandbox0.managed_agents.engine` on the LLM vault. |
| Sandbox claim | Runtime setup claims or resumes a Sandbox0 sandbox and mounts a persistent workspace volume. |
| Claude harness | Requires an Anthropic-compatible endpoint. |
| Codex harness | Requires an OpenAI-compatible endpoint. |
| OpenAI Agents harness | Requires an OpenAI Responses-compatible endpoint and uses Sandbox0 as a tool target. |
| Retry state | Automatic retries are exposed as `session.status_rescheduled` plus `retry_status.type = "retrying"` errors when the selected harness provides a retry signal. |
| External AI gateway | Optional. Use one when provider API shape, provider credentials, logging, caching, or rate limits should be managed outside Sandbox0. |
| Anthropic pre-built skills | Not supported. Use Sandbox0 custom skills. |
| Multi-agent threads | Not implemented in the current backend surface. |
| Outcomes and memory research preview | Not implemented in the current backend surface. |
| Rate limits | Deployment-specific. Do not assume Anthropic-hosted organization limits apply. |

## Tool Support

The Claude wrapper maps Managed Agents tool definitions to Claude Agent SDK options.

| Tool type | Status | Notes |
|-----------|--------|-------|
| `agent_toolset_20260401` | Supported | Enables built-in tools such as bash, file operations, grep/glob, web fetch, and web search through the selected harness wrapper |
| `mcp_toolset` | Supported | Requires matching `mcp_servers` entries and vault credentials when the server needs auth |
| Custom tools | Supported | The wrapper emits `agent.custom_tool_use` and waits for `user.custom_tool_result` |

Tool confirmation events are supported. When a tool policy requires confirmation, the session emits `session.status_idle` with `stop_reason.type = "requires_action"` and the relevant event ids.

## Environment Support

Only `type: cloud` environments are accepted today.

Networking options:

| Networking type | Behavior |
|-----------------|----------|
| `unrestricted` | Sandbox network mode is `allow-all` |
| `limited` | Sandbox network mode is `block-all` with allowed hosts derived from environment settings, package managers, MCP servers, and session credential bindings |

Package managers supported in environment config:

- `apt`
- `cargo`
- `gem`
- `go`
- `npm`
- `pip`

## Metadata Rules

Only vault metadata supports reserved `sandbox0.managed_agents.*` keys today.

| Resource | Reserved keys |
|----------|---------------|
| Agent | Rejected |
| Environment | Rejected |
| Session | Rejected |
| Credential | Rejected |
| Vault | Supported for LLM and credential vault config |

## Vault Compatibility

| Vault role | Required metadata |
|------------|-------------------|
| `llm` | `role`, `engine`, optional `llm_base_url` |
| `credential` | `role`, `kind=http_headers`, `target_domains`, `headers_json` |

LLM vaults must contain exactly one active `static_bearer` credential and must not set `mcp_server_url`.

## Session Lifecycle Notes

Sandbox0 stores the session and event log outside the sandbox. Sandbox attachment state is stored outside the sandbox and points at the sandbox and volumes.

| Action | Behavior |
|--------|----------|
| Create session | Stores durable session truth, snapshots the agent, and records environment, resources, and vault ids. |
| Send user message | Ensures a sandbox is ready, bootstraps wrapper state, starts a run, and appends status events. |
| Interrupt | Interrupts the active wrapper run and moves local session truth back toward idle. |
| Delete | Rejects active running sessions. Delete after interrupting and reaching idle. |
| Archive | Makes the session read-only for new input events. |

`claude` and `codex` use agent in sandbox behavior. `openai-agents` uses sandbox as tool behavior, so the resident runtime can start a run before a Sandbox0 sandbox is claimed.

Sandbox0 session lifecycle includes `idle`, `running`, `rescheduling`, and `terminated`. The `rescheduling` state is transient and means the active run is waiting for an automatic retry. It is currently mapped from Claude Agent SDK `api_retry` events, Codex app-server `willRetry` errors, and OpenAI Agents SDK runner-managed retry policy decisions.

## Version Drift

The Managed Agents API is a beta surface. Sandbox0 tracks the official OpenAPI shape, but behavior can differ where Sandbox0 intentionally uses its own runtime, credential, and deployment model.

For application code, prefer SDK methods over hardcoded endpoint paths.

## Next Steps

<CardGroup>
  <Card title="Overview" href="/docs/credential" cta="Continue">
    Learn the credential model used by sandbox egress auth and managed agent vaults.
  </Card>

  <Card title="Sources" href="/docs/credential/sources" cta="Continue">
    Create reusable credential sources for runtime projection.
  </Card>
</CardGroup>
