#Agent Engines

An agent engine is the Sandbox0 runtime adapter behind a Managed Agents session.

The public API still uses the Claude Managed Agents object model. The engine decides where the agent loop runs, which model API shape it expects, how credentials are projected, and how tool events are mapped back to the Managed Agents event stream.

Official references:

• Claude Managed Agents quickstart
• Claude Managed Agents agent setup

Execution Models#

Sandbox0 supports two execution models.

Use agent in sandbox when you want the agent process itself to live with the workspace. This is the most direct fit for coding agents that expect local files, shell commands, home-directory state, and long-lived process state inside the sandbox.

Use sandbox as tool when you want to embed an agent into a product workflow or control plane. The agent harness stays in a managed runtime service, while Sandbox0 provides isolated tool execution only when the agent needs to inspect files or run commands.

Supported Engines#

Retry Behavior#

All supported engines report observable automatic retry attempts through the same Managed Agents events: session.error with error.retry_status.type = "retrying", session.status_rescheduled, then session.status_running if the run resumes.

Sandbox0 disables hidden OpenAI Python client retries for the openai-agents runtime and routes model retries through the OpenAI Agents SDK retry policy so retry state is visible in the session event stream.

Select An Engine#

The session engine is selected by the attached LLM vault:

typescript
const claudeVault = await client.beta.vaults.create({
    display_name: "Claude LLM",
    metadata: {
        "sandbox0.managed_agents.role": "llm",
        "sandbox0.managed_agents.engine": "claude",
        "sandbox0.managed_agents.llm_base_url": "https://api.anthropic.com",
    },
});

For codex:

typescript
const codexVault = await client.beta.vaults.create({
    display_name: "Codex LLM",
    metadata: {
        "sandbox0.managed_agents.role": "llm",
        "sandbox0.managed_agents.engine": "codex",
        "sandbox0.managed_agents.llm_base_url": "https://api.openai.com/v1",
    },
});

For openai-agents:

typescript
const openAIAgentsVault = await client.beta.vaults.create({
    display_name: "OpenAI Agents LLM",
    metadata: {
        "sandbox0.managed_agents.role": "llm",
        "sandbox0.managed_agents.engine": "openai-agents",
        "sandbox0.managed_agents.llm_base_url": "https://api.openai.com/v1",
    },
});

Add the model provider token to the selected LLM vault:

typescript
await client.beta.vaults.credentials.create(openAIAgentsVault.id, {
    display_name: "Model provider API key",
    auth: {
        type: "static_bearer",
        token: process.env.MODEL_API_KEY!,
    } as any,
});

Use the vault id for the engine you want. LLM credentials must be unbound static_bearer credentials; do not set mcp_server_url for the model provider token.

Attach exactly one LLM vault to the session:

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

If no LLM vault selects an engine, Sandbox0 defaults to claude.

Claude Engine#

The Claude engine runs the Claude Agent SDK wrapper inside the session sandbox. It expects an Anthropic-compatible API. Use it when the provider already exposes the Anthropic Messages API shape and you want Claude Code style behavior.

Sandbox0 sets compatibility environment values such as ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, and ANTHROPIC_BASE_URL, then injects the real credential through egress auth for the configured LLM host.

Codex Engine#

The Codex engine launches Codex app-server inside the session sandbox. It expects an OpenAI-compatible model endpoint. Sandbox0 stores Codex home and thread state under the session workspace so runtime state stays session-scoped.

For Minimax-compatible endpoints, Sandbox0 detects the provider from the LLM base URL and configures Codex provider settings accordingly.

OpenAI Agents Engine#

The openai-agents engine uses a resident Python runtime service built on the official OpenAI Agents SDK. The runtime receives the session snapshot from the Managed Agents gateway, runs the agent loop in the runtime service, and claims a Sandbox0 sandbox only when the agent needs sandbox tools.

This is the sandbox as tool model. The session still has durable Managed Agents event history, but the agent process is not the same process as the sandbox. The sandbox is an isolated tool target for commands and workspace work.

The engine expects an OpenAI Responses-compatible endpoint. For Anthropic-compatible providers, place LLMProxy in front of the provider and store the proxy URL as the LLM vault base URL.

typescript
const zaiViaLLMProxyVault = await client.beta.vaults.create({
    display_name: "Z.ai through LLMProxy",
    metadata: {
        "sandbox0.managed_agents.role": "llm",
        "sandbox0.managed_agents.engine": "openai-agents",
        "sandbox0.managed_agents.llm_base_url": "https://llmproxy.sandbox0.ai/claude2codex/https://api.z.ai/api/anthropic",
    },
});

Engine Configuration#

Agent engine behavior can be configured by deployment defaults and internal engine config. Application-level engine selection should normally happen through the LLM vault, not by putting reserved Sandbox0 keys into session metadata.

Next Steps#