claude-code-server

Production-ready HTTP API server for Claude Code CLI. Exposes Claude's agentic coding capabilities as a secure REST API with streaming, configuration management, and bounded concurrency.

Why?

Claude Code CLI is powerful but limited to terminal usage. This server turns it into a headless API you can integrate into CI/CD pipelines, chatbots, internal tools, or any HTTP client — while adding security, concurrency control, and configuration management that the CLI doesn't provide.

What makes it different

Architecture

Client → [TLS + Basic Auth (Traefik)] → claude-code-server (Fastify)
                                              │
                    ┌─────────────────────────┤
                    │                         │
              POST /ask                 /config/*
                    │                         │
            ┌───────┴───────┐          Config Store
            │  Semaphore    │          (filesystem)
            │  (bounded     │               │
            │  concurrency) │          /home/node/.claude/
            │               │          ├── agents/
            ▼               │          ├── skills/
     spawn claude CLI       │          ├── rules/
     ├── sync (JSON)        │          └── CLAUDE.md
     └── stream (SSE)      │
                            │
                     /workspace/
                     (git repos)

Quick start

Docker

docker run -d \
  -e API_KEY=your-secret-key \
  -e ANTHROPIC_API_KEY=your-anthropic-key \
  -p 3000:3000 \
  ghcr.io/billyboy06/claude-code-server:latest

From source

git clone https://github.com/billyboy06/claude-code-server.git
cd claude-code-server
npm install
API_KEY=your-secret-key node src/server.js

Prerequisite: Claude Code CLI must be installed and configured (npm install -g @anthropic-ai/claude-code).

API reference

Authentication

All endpoints (except /health) require an x-api-key header:

curl -H "x-api-key: $API_KEY" http://localhost:3000/config/agents

GET /health

Returns server status and concurrency info.

{
  "status": "ok",
  "version": "0.2.0",
  "concurrency": { "active": 1, "max": 3, "queued": 0 }
}

POST /ask

Send a prompt to Claude Code.

curl -X POST http://localhost:3000/ask \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Explain the main function in src/server.js",
    "cwd": "my-project",
    "maxTurns": 10
  }'

Parameters:

Streaming (SSE):

curl -N -X POST http://localhost:3000/ask \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hello", "stream": true}'

Events: data (JSON chunks), error, done.

Configuration management

CRUD API for Claude Code configuration files (agents, skills, rules, CLAUDE.md).

Example — deploy a custom agent:

curl -X PUT http://localhost:3000/config/agents/code-reviewer \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "---\nname: code-reviewer\ndescription: Reviews code for quality\n---\n\nYou are an expert code reviewer..."
  }'

Then use it:

curl -X POST http://localhost:3000/ask \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Review src/server.js", "agent": "code-reviewer"}'

Configuration

Claude Code credentials

The server spawns the claude CLI as a child process. The CLI needs valid Anthropic credentials to work. There are two ways to set this up:

Option 1 — Environment variable (simplest)

Pass your Anthropic API key as an environment variable. The server forwards it to the CLI process automatically:

docker run -d \
  -e API_KEY=your-server-api-key \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -p 3000:3000 \
  ghcr.io/billyboy06/claude-code-server:latest

Option 2 — Claude CLI config (persistent, recommended for Kubernetes)

Run claude interactively once to authenticate, then mount the resulting config directory. The CLI stores its credentials in ~/.claude/:

# 1. Authenticate locally
npm install -g @anthropic-ai/claude-code
claude  # follow the interactive login flow

# 2. Mount the config into the container
docker run -d \
  -e API_KEY=your-server-api-key \
  -v ~/.claude:/home/node/.claude \
  -p 3000:3000 \
  ghcr.io/billyboy06/claude-code-server:latest

On Kubernetes, use a PVC mounted at /home/node/.claude to persist the credentials across restarts. This also stores the configuration files managed by the /config/* API.

Which option to choose?

Pro/Max subscription tip: If you use Claude Pro ($20/mo) or Max ($100/mo), authenticate via Option 2. The CLI uses your subscription directly — no per-token API charges. This is the most cost-effective setup for teams.

Security

• Timing-safe API key comparison (crypto.timingSafeEqual)
• Path traversal prevention with realpath resolution and workspace whitelisting
• Rate limiting — 10 req/min on /ask, 60 req/min on /config/*
• Security headers via @fastify/helmet (HSTS, X-Frame-Options, CSP, etc.)
• Environment whitelist — child processes only see PATH, HOME, NODE_ENV, ANTHROPIC_API_KEY
• Input validation — JSON schemas on all endpoints, name pattern enforcement
• Flag injection prevention — -- separator before prompt in CLI args
• Non-root container (USER node)

Deployment

Kubernetes (Helm)

The server is designed for Kubernetes deployment with:

• PVC for persistent config at /home/node/.claude
• emptyDir for workspace at /workspace (clone repos via init containers)
• Ingress with TLS termination and optional basic auth middleware

GitHub Actions CI/CD

Automated build and push to GHCR on every push to main. See .github/workflows/build.yml.

Project structure

src/
├── server.js              # Fastify bootstrap, plugins, routes
├── plugins/
│   └── auth.js            # x-api-key authentication hook
├── routes/
│   ├── health.js          # GET /health
│   ├── ask.js             # POST /ask (sync + SSE streaming)
│   └── config.js          # /config/* CRUD endpoints
├── services/
│   ├── claude.js           # Claude CLI spawn (sync + stream)
│   └── configStore.js     # Filesystem CRUD for .claude/
├── lib/
│   ├── validation.js      # Path safety, name validation
│   └── semaphore.js       # Bounded concurrency queue
└── schemas/
    ├── ask.js             # JSON schema for POST /ask
    └── config.js          # JSON schemas for /config/*

License

MIT