Claudebox Turns Your Claude Code Subscription Into a Local API Server

What Claudebox Does

Claudebox is an open-source tool that runs Claude Code inside a network-isolated Docker container and exposes it as an HTTP API. This means you can use your Claude subscription as a backend for any tool that speaks the OpenAI API format, without paying for separate API credits.

The key innovation: it authenticates using your existing Claude CLI credentials (~/.claude/.credentials.json or macOS Keychain), so there's no API key management or additional billing. The container is sandboxed—Claude gets its full agent toolset (file editing, shell access, code analysis) but can't access your host machine or the open internet beyond Anthropic's domains.

Why This Matters for Claude Code Users

If you're already paying for Claude Max ($20-200/month), you're getting significant value. A recent analysis of 80 autonomous coding tasks found that the weekly utilization limit on a $200 Max plan is worth about $1,100 in equivalent API pricing—roughly 22x what you pay. Individual tasks averaged $2.66 for implementation and $0.57 for code review.

Claudebox lets you leverage this subscription value programmatically. Instead of only using Claude Code interactively from your terminal, you can now:

• Build custom automation scripts that call Claude as an agent
• Integrate Claude into existing Docker Compose stacks alongside other services
• Use any OpenAI-compatible client (like LangChain, LlamaIndex, or custom apps) with Claude as the backend

How to Install and Use It

Quick Start (CLI Mode)

# Install Claudebox
curl -fsSL https://raw.githubusercontent.com/ArmanJR/claudebox/main/install.sh | bash

# Run a single prompt
claudebox prompt "explain how DNS works"

# Start the HTTP server
claudebox server

# Start with OpenAI-compatible endpoints
claudebox server --openai

The CLI handles authentication automatically by reading your existing Claude credentials. It works on macOS and Linux.

Docker Compose Integration

For more complex setups where you want Claude as a service alongside other containers:

# First, extract your OAuth token
curl -fsSL https://raw.githubusercontent.com/ArmanJR/claudebox/main/setup-auth.sh | bash

Then create a docker-compose.yml:

services:
  claudebox:
    image: ghcr.io/armanjr/claudebox:latest
    cap_add:
      - NET_ADMIN
    ports:
      - "3000:3000"
    env_file:
      - path: .env.claude
        required: true

Other services in the same network can reach Claude at http://claudebox:3000.

API Usage Examples

Native Claudebox API

curl -X POST http://localhost:3000/prompt \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Write a Python function to validate email addresses",
    "options": {
      "model": "sonnet",
      "maxTurns": 10,
      "allowedTools": ["Read", "Edit", "Bash"],
      "cwd": "/workspace"
    }
  }'

All options fields are optional. The response includes Claude Code's full JSON output with result, session_id, usage, and total_cost_usd.

OpenAI-Compatible Mode

When you start the server with --openai flag or set OPENAI_COMPAT=1 in Docker, you get standard OpenAI endpoints:

curl http://localhost:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

This makes Claudebox drop-in compatible with hundreds of existing AI tools and frameworks.

When to Use Claudebox

1. Personal Data Processing: The creator uses it for "personal data processing tasks where I want an agent API but don't want to pay above my subscription."
2. Batch Operations: Run Claude on multiple files or datasets programmatically
3. Integration Testing: Test how your application interacts with Claude without manual prompting
4. Workflow Automation: Build custom pipelines where Claude performs specific agentic tasks

Security Considerations

The Docker container is network-isolated by default—only Anthropic domains are allowed. Claude gets its full toolset inside the container but can't access your host filesystem or other network resources. Your credentials stay local and are refreshed automatically when needed.

Limitations

• Requires Docker and the Claude CLI already installed and authenticated
• Token usage counts against your Claude subscription's weekly utilization
• Currently macOS and Linux only (no Windows support mentioned)
• The OAuth token for Docker Compose needs periodic refreshing

Claudebox represents a clever workaround for developers who want programmatic access to Claude's agent capabilities without the per-token costs of the official API. It's essentially turning your subscription's "unlimited" usage (within limits) into a local API server.