Self-Hosted Claude Code: Run on Your Infrastructure

Cloud deployments (AWS SageMaker, Azure ML, GCP Vertex) are convenient but violate some organizations' requirements. Self-hosted means you control every layer: compute, storage, network, and credentials stay in your data centers.

Trade-offs: self-hosted requires more ops work. You manage infrastructure, patching, backups, and failover. But it gives you:

• Data residency: all code and context stay in your country/region.
• Air-gapped security: no internet egress unless you explicitly allow it.
• Compliance: HIPAA, SOC 2, PCI-DSS audits see your infrastructure, not a third-party's.
• Custom networking: integrate with your VPN, reverse proxies, and legacy systems.

A Claude Code runner is a Docker container or VM that executes code in isolation. It receives a request (user code, context, model), spawns a sandbox, runs the code, captures output, and returns it to the control plane.

Runners need: Docker or a container runtime, Python 3.10+, git client, and the Claude Code agent SDK. Build a base image with these, then run it as a pod (Kubernetes) or container (Docker Compose).

The image contains: dependencies, configuration templates, health check scripts, and logging agents. Size it 2–4 GB to keep startup latency under 5 seconds.

Self-hosted runners need to: (1) pull dependencies (pip packages, git repos), (2) authenticate to private git repos, and (3) optionally send telemetry/logs to central services.

Network egress is controlled. If your network is air-gapped, allow specific egress rules (package registries, git servers, logging services). If not, all traffic flows through a proxy.

Git credentials must not be baked into the image. Use environment variables or a credential helper. For Kubernetes, store credentials in Secrets. For Docker Compose, use a .env file (excluded from Git).

Private git repos require SSH keys or tokens. Mount the SSH key from a Kubernetes Secret, or inject it at container startup. Rotate keys every 90 days.

For Kubernetes deployments, two patterns:

DaemonSet: one runner pod per node. Good if every node should be able to run code. Runners share node resources (CPU, memory). Use this for uniform clusters.

Job: ephemeral pods spawned on-demand. Each request spawns a new pod, runs code, and exits. Good if traffic is bursty or you want strict isolation per request.

We recommend StatefulSet (covered earlier) for production: named pods, persistent cache, and orderly scaling.

For teams <50 engineers, Docker Compose on a single machine is simpler than Kubernetes. Define all services (runners, control plane, Redis, database) in one file, and manage with docker-compose commands.

Caveats: single-node failure is total outage. No auto-scaling. Good for dev/test or on-prem teams with low traffic.

For production <50 engineers, consider: Docker Compose on a machine with SSD and 32GB RAM, daily snapshots to S3, and a hot-standby machine ready to restore.

Runners must trust that requests come from authenticated users. When the control plane forwards a request to a runner, it includes a JWT signed by the control plane. The runner validates the signature to confirm the control plane is legitimate (not a man-in-the-middle).

JWT payload includes: user_id, team, session_id, issued_at, expires_at. The runner checks: signature is valid, token is not expired, user is allowed to run code.

For mutual TLS (mTLS), both control plane and runners exchange certificates. This is more secure but requires certificate management.

Self-hosted isn't free. Compute: each runner pod costs money (server, power, colocation). Bandwidth: egress to git servers, package registries, and logging. Maintenance: patching, backups, monitoring, on-call support.

For 500 engineers, estimate: 3–5 large servers ($20K/year), bandwidth ($5K/year), managed database ($10K/year), backup storage ($2K/year), and 1 FTE for ops ($150K/year). Total: ~$200K/year.

Cloud deployment: similar traffic on AWS = $150K/year in compute + management by AWS. If you have on-prem infrastructure already, self-hosted marginal cost is lower; otherwise, cloud is more cost-effective.

Common issues:

1. Runners crash on startup: check logs for missing dependencies or credentials. Verify Docker image includes all required packages.

2. Slow code execution: runner CPU/memory limits too low, or underlying node is overloaded. Check Kubernetes metrics (kubectl top nodes); increase resource requests.

3. Git credential failures: SSH key expired or not mounted. Verify Secret exists; check runner logs for "Permission denied" errors.

4. Control plane can't reach runners: network policy blocking traffic, or runners not healthy (failed health checks). Use kubectl port-forward to test connectivity.

5. Data residency violation: code/context sent outside your network. Check firewall rules; enable egress logging to audit traffic.

Monitor: runner CPU, memory, disk (cache), latency per request, error rate, and unauthorized access attempts.