sandbox-agent/docs/credentials.mdx

---
title: "Credentials"
description: "How sandbox-agent discovers and uses provider credentials."
icon: "key"
---

Sandbox-agent automatically discovers API credentials from environment variables and agent config files. Credentials are used to authenticate with AI providers (Anthropic, OpenAI) when spawning agents.

## Credential sources

Credentials are extracted in priority order. The first valid credential found for each provider is used.

### Environment variables (highest priority)

**API keys** (checked first):

| Variable | Provider |
|----------|----------|
| `ANTHROPIC_API_KEY` | Anthropic |
| `CLAUDE_API_KEY` | Anthropic (fallback) |
| `OPENAI_API_KEY` | OpenAI |
| `CODEX_API_KEY` | OpenAI (fallback) |

**OAuth tokens** (checked if no API key found):

| Variable | Provider |
|----------|----------|
| `CLAUDE_CODE_OAUTH_TOKEN` | Anthropic (OAuth) |
| `ANTHROPIC_AUTH_TOKEN` | Anthropic (OAuth fallback) |

OAuth tokens from environment variables are only used when `include_oauth` is enabled (the default).

### Agent config files

If no environment variable is set, sandbox-agent checks agent-specific config files:

| Agent | Config path | Provider |
|-------|-------------|----------|
| Amp | `~/.amp/config.json` | Anthropic |
| Claude Code | `~/.claude.json`, `~/.claude/.credentials.json` | Anthropic |
| Codex | `~/.codex/auth.json` | OpenAI |
| OpenCode | `~/.local/share/opencode/auth.json` | Both |

OAuth tokens are supported for Claude Code, Codex, and OpenCode. Expired tokens are automatically skipped.

## Provider requirements by agent

| Agent | Required provider |
|-------|-------------------|
| Claude Code | Anthropic |
| Amp | Anthropic |
| Codex | OpenAI |
| OpenCode | Anthropic or OpenAI |
| Mock | None |

## Error handling behavior

Sandbox-agent uses a **best-effort, fail-forward** approach to credentials:

### Extraction failures are silent

If a config file is missing, unreadable, or malformed, extraction continues to the next source. No errors are thrown. Missing credentials simply mean the provider is marked as unavailable.

```
~/.claude.json missing     → try ~/.claude/.credentials.json
~/.claude/.credentials.json missing → try OpenCode config
All sources exhausted      → anthropic = None (not an error)
```

### Agents spawn without credential validation

When you send a message to a session, sandbox-agent does **not** pre-validate credentials. The agent process is spawned with whatever credentials were found (or none), and the agent's native error surfaces if authentication fails.

This design:
- Lets you test agent error handling behavior
- Avoids duplicating provider-specific auth validation
- Ensures sandbox-agent faithfully proxies agent behavior

For example, sending a message to Claude Code without Anthropic credentials will spawn the agent, which will then emit its own "ANTHROPIC_API_KEY not set" error through the event stream.

## Checking credential status

### API endpoint

The `GET /v1/agents` endpoint includes a `credentialsAvailable` field for each agent:

```json
{
  "agents": [
    {
      "id": "claude",
      "installed": true,
      "credentialsAvailable": true,
      ...
    },
    {
      "id": "codex",
      "installed": true,
      "credentialsAvailable": false,
      ...
    }
  ]
}
```

### TypeScript SDK

```typescript
const { agents } = await client.listAgents();
for (const agent of agents) {
  console.log(`${agent.id}: ${agent.credentialsAvailable ? 'authenticated' : 'no credentials'}`);
}
```

### OpenCode compatibility

The `/opencode/provider` endpoint returns a `connected` array listing providers with valid credentials:

```json
{
  "all": [...],
  "connected": ["claude", "mock"]
}
```

## Passing credentials explicitly

You can override auto-discovered credentials by setting environment variables before starting sandbox-agent:

```bash
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
sandbox-agent daemon start
```

Or when using the SDK in embedded mode:

```typescript
const client = await SandboxAgentClient.spawn({
  env: {
    ANTHROPIC_API_KEY: process.env.MY_ANTHROPIC_KEY,
  },
});
```