Documentation/docs/managed-agents/vaults

#Vaults

Vaults keep credentials out of agent code. Attach vault ids to a session, and Sandbox0 projects the matching credentials into network policy for that session.

Official reference: Claude Managed Agents vaults.

LLM Vaults#

Every running session should attach exactly one LLM vault. The LLM vault selects the agent engine and model provider endpoint.

typescript
const llmVault = 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",
    },
});

await client.beta.vaults.credentials.create(llmVault.id, {
    display_name: "Anthropic API key",
    auth: {
        type: "static_bearer",
        token: process.env.MODEL_API_KEY!,
    } as any,
});
Metadata keyRequiredMeaning
sandbox0.managed_agents.roleYesMust be llm for an LLM vault
sandbox0.managed_agents.engineYesclaude, codex, or openai-agents
sandbox0.managed_agents.llm_base_urlNoModel provider base URL

The LLM credential must be an unbound static_bearer credential. Do not set mcp_server_url on LLM credentials.

ℹ

The as any cast on unbound static_bearer credentials is intentional for current Anthropic TypeScript SDK types. Sandbox0 LLM and generic HTTP credential vaults omit mcp_server_url.

Generic Credential Vaults#

Use credential vaults when the agent needs authenticated outbound access to an external HTTP service.

typescript
const apiVault = await client.beta.vaults.create({
    display_name: "Example API",
    metadata: {
        "sandbox0.managed_agents.role": "credential",
        "sandbox0.managed_agents.kind": "http_headers",
        "sandbox0.managed_agents.version": "1",
        "sandbox0.managed_agents.target_domains": "api.example.com",
        "sandbox0.managed_agents.protocol": "https",
        "sandbox0.managed_agents.tls_mode": "terminate-reoriginate",
        "sandbox0.managed_agents.failure_policy": "fail-closed",
        "sandbox0.managed_agents.headers_json": "{\"authorization\":\"{{ .authorization }}\"}",
    },
});

await client.beta.vaults.credentials.create(apiVault.id, {
    display_name: "Example API token",
    auth: {
        type: "static_bearer",
        token: process.env.EXAMPLE_API_TOKEN!,
    } as any,
});

Credential vaults can use static_bearer or mcp_oauth credentials. Sandbox0 resolves secret values and projects headers only for the target domains.

MCP Credentials#

For MCP servers, the credential auth includes mcp_server_url.

typescript
await client.beta.vaults.credentials.create(vault.id, {
    display_name: "MCP token",
    auth: {
        type: "static_bearer",
        token: process.env.MCP_TOKEN!,
        mcp_server_url: "https://mcp.example.com/sse",
    },
});

Runtime Injection#

Sandbox0 injects credentials through egress auth and compatibility environment variables:

EngineCompatibility environment
claudeANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL
codexCODEX_API_KEY, OPENAI_API_KEY, and openai_base_url engine config
openai-agentsOPENAI_API_KEY, OPENAI_BASE_URL, and openai_base_url engine config

The environment variables may contain placeholders. The real token is projected by Sandbox0-managed credential policy when the sandbox contacts the configured host.

For openai-agents, the runtime expects an OpenAI Responses-compatible base URL. If the provider exposes an Anthropic-compatible endpoint, use LLMProxy and store the LLMProxy URL in sandbox0.managed_agents.llm_base_url.

Next Steps#

Agent Engines

Choose the runtime adapter that should execute each managed session.

LLMProxy

Translate Anthropic-compatible model providers for OpenAI-compatible engines.