---

name: zero-credential-claude description: Explains how Claude Code works in containers with zero credentials via the clauderon proxy. Use when testing Claude in containers, debugging authentication issues, or understanding the zero-trust proxy architecture.

Zero-Credential Claude Code in Containers

Overview

Clauderon enables Claude Code to run in Docker containers with zero real credentials. The host proxy intercepts HTTPS requests and injects authentication, so containers never see actual API keys or tokens.

Architecture

CopyContainer (placeholder creds) → HTTPS Proxy (TLS intercept) → api.anthropic.com
                                       ↓
                              Inject: Authorization: Bearer {real_oauth_token}

How It Works

1. OAuth Token Loading

The daemon loads the real OAuth token from CLAUDE_CODE_OAUTH_TOKEN environment variable on the host:

Copy// src/proxy/config.rs
anthropic_oauth_token: std::env::var("CLAUDE_CODE_OAUTH_TOKEN").ok(),

2. Container Setup

Containers receive placeholder credentials that make Claude Code think it's authenticated:

Copy// src/backends/docker.rs
"-e", "CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-clauderon-proxy-placeholder"

A claude.json file is mounted to skip onboarding:

Copy{"hasCompletedOnboarding": true}

3. Container Mounts (Security)

Containers receive minimal mounts for security. The base ~/.clauderon/ directory is NOT mounted. Only specific files/directories are mounted:

Mounted (Required for functionality):

Copy# Uploads directory (bidirectional communication)
-v ~/.clauderon/uploads:/workspace/.clauderon/uploads

# Proxy CA certificate (for TLS interception)
-v ~/.clauderon/proxy-ca.pem:/etc/clauderon/proxy-ca.pem:ro

# Codex dummy config (real tokens injected by proxy)
-v ~/.clauderon/codex:/etc/clauderon/codex:ro

# Claude configuration (onboarding and permissions)
-v ~/.clauderon/claude.json:/workspace/.claude.json

NOT Mounted (Security reasons):

• ~/.clauderon/secrets/ - Real OAuth tokens and API keys stay on host
• ~/.clauderon/db.sqlite - Session database
• ~/.clauderon/audit.jsonl - Proxy audit logs
• ~/.clauderon/*.sock - Unix sockets for daemon IPC
• ~/.clauderon/proxy-ca-key.pem - CA private key

Hooks directory: The /workspace/.clauderon/hooks/ directory is created inside containers via docker exec, not via mount. This ensures hooks are isolated per container.

4. Proxy Credential Injection

The HTTP proxy intercepts requests to api.anthropic.com and:

1. Removes any existing auth headers (placeholder credentials)
2. Injects OAuth token with Bearer auth

Copy// src/proxy/http_proxy.rs - Anthropic uses Bearer auth for OAuth
req.headers_mut().remove("authorization");
("authorization", format!("Bearer {}", token))

5. Execution Modes

The Docker backend supports two execution modes:

Interactive Mode (default)

Containers run Claude Code interactively, allowing you to attach and have a conversation:

Copyclaude --dangerously-skip-permissions 'initial prompt here'

After the session is created, attach to interact with Claude:

Copyclauderon attach <session-name>
# Or directly with docker:
docker attach clauderon-<session-name>

Non-Interactive (Print) Mode

For CI/CD pipelines or scripted usage, use print mode. The container outputs the response and exits:

Copyclaude --dangerously-skip-permissions --print --verbose 'prompt here'

To enable print mode programmatically:

Copy// src/backends/docker.rs
let backend = DockerBackend::with_proxy(proxy_config)
    .with_print_mode(true);

Print mode is useful for:

• CI/CD pipelines where interactive input isn't possible
• Automated testing
• One-shot queries that don't need follow-up

Testing Claude in Containers

Prerequisites

1. Set your OAuth token on the host:

   Copyexport CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-your-real-token
   

2. Start the clauderon daemon:

   Copycargo run --bin clauderon daemon
   

Create a Test Session

Copycargo run --bin clauderon create --name test-session --prompt "Say hello"

Manual Container Test

To manually test without creating a full session:

Copy# Start the daemon first
cargo run --bin clauderon daemon &

# Run a container with the proxy setup
docker run -it --rm \
  -e CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-clauderon-proxy-placeholder \
  -e HTTPS_PROXY=http://host.docker.internal:18080 \
  -e HTTP_PROXY=http://host.docker.internal:18080 \
  -v ~/.clauderon/proxy-ca.pem:/etc/ssl/certs/clauderon-proxy-ca.pem:ro \
  -v ~/.clauderon/claude.json:/root/.claude.json \
  your-claude-image \
  claude --print "Hello, Claude!"

Verify Proxy is Injecting Credentials

Check the audit log at ~/.clauderon/audit.jsonl:

Copytail -f ~/.clauderon/audit.jsonl | jq

Look for entries with "auth_injected": true for api.anthropic.com requests.

Debug Container Issues

1. Check daemon logs for proxy activity
2. Verify CA cert is trusted in container: curl -v https://api.anthropic.com
3. Check environment in container: env | grep -E '(PROXY|CLAUDE)'

Common Issues

"OAuth authentication is currently not supported"

The proxy is using x-api-key header instead of Authorization: Bearer. Ensure:

• Token starts with sk-ant-oat01-
• Proxy rules are updated to use Bearer auth

Onboarding Prompt Appears

The claude.json file is missing or not mounted. Verify:

Copycat ~/.clauderon/claude.json
# Should contain: {"hasCompletedOnboarding": true}

"Do you want to use this API key?" Prompt

Using ANTHROPIC_API_KEY instead of CLAUDE_CODE_OAUTH_TOKEN. The latter triggers OAuth flow detection and skips this prompt.

Read-Only Filesystem Error

The claude.json mount must NOT be read-only (:ro). Claude Code writes to this file.

Key Files