---
title: "Credentials"
description: "How Sandbox Agent discovers and uses provider credentials."
---

Sandbox Agent discovers API credentials from environment variables and local agent config files.
These credentials are passed through to underlying agent runtimes.

## Credential sources

Credentials are discovered in priority order.

### Environment variables (highest priority)

API keys first:

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

OAuth tokens (used when OAuth extraction is enabled):

| Variable | Provider |
|----------|----------|
| `CLAUDE_CODE_OAUTH_TOKEN` | Anthropic |
| `ANTHROPIC_AUTH_TOKEN` | Anthropic fallback |

### Agent 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` | Anthropic/OpenAI |

## Provider requirements by agent

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

## Error handling behavior

Credential extraction is best-effort:

- Missing or malformed files are skipped.
- Discovery continues to later sources.
- Missing credentials mark providers unavailable instead of failing server startup.

When prompting, Sandbox Agent does not pre-validate provider credentials. Agent-native authentication errors surface through session events/output.

## Checking credential status

### API

`sdk.listAgents()` includes `credentialsAvailable` per agent.

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

### TypeScript SDK

```typescript
const result = await sdk.listAgents();

for (const agent of result.agents) {
  console.log(`${agent.id}: ${agent.credentialsAvailable ? "authenticated" : "no credentials"}`);
}
```

## Passing credentials explicitly

Set environment variables before starting Sandbox Agent:

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

Or with SDK-managed local spawn:

```typescript
import { SandboxAgent } from "sandbox-agent";

const sdk = await SandboxAgent.start({
  spawn: {
    env: {
      ANTHROPIC_API_KEY: process.env.MY_ANTHROPIC_KEY,
    },
  },
});
```