Running Claude Code in Docker and Dev Containers Against an Aggregator Endpoint

Why Run Claude Code in a Container?

Running Claude Code inside Docker or a dev container isolates dependencies, ensures consistent tooling across teams, and integrates with existing container-based workflows. However, when you point Claude Code at an aggregator endpoint instead of the official API, you need to handle endpoint configuration, key injection, and networking carefully.

Injecting the Endpoint and Key

Claude Code reads its configuration from environment variables. To use an aggregator, set:

• ANTHROPICBASEURL to your aggregator's API base URL (e.g., https://api.your-aggregator.com).
• ANTHROPICAPIKEY to your aggregator-issued key, which starts with sk-.

In a Dockerfile, you can set the base URL as an ENV instruction, but never hardcode the API key. Instead, pass it at runtime with -e ANTHROPICAPIKEY=your_key or use an env file.

For dev containers, add these variables to your devcontainer.json under containerEnv or remoteEnv. Use ${localEnv:ANTHROPICAPIKEY} to forward the key from your host environment, keeping it out of version control.

Docker Networking Pitfalls

When Claude Code runs inside a container, it needs to reach the aggregator endpoint over the network. Common issues include:

• DNS resolution: Containers use the host's DNS by default, but custom networks may need explicit DNS servers. If resolution fails, try --dns 8.8.8.8 or configure Docker daemon settings.
• Host network mode: On Linux, --network host makes the container share the host's network stack, simplifying access to services on localhost. On macOS and Windows, host networking is limited or unavailable, so use host.docker.internal to reach the host.
• Proxy interference: If your environment uses an HTTP proxy, Docker containers won't inherit host proxy settings automatically. Set HTTPPROXY, HTTPSPROXY, and NOPROXY as environment variables in the container. Ensure NOPROXY includes the aggregator domain if it should bypass the proxy.
• Firewall rules: Outbound connections to the aggregator's domain must be allowed. Check both host and container firewall configurations.

Dev Container Specifics

Dev containers add a layer of abstraction. The remoteEnv property in devcontainer.json sets variables for the editor and terminal sessions inside the container. Use it to inject the API key without baking it into the image:

{
  "remoteEnv": {
    "ANTHROPIC_BASE_URL": "https://api.your-aggregator.com",
    "ANTHROPIC_API_KEY": "${localEnv:ANTHROPIC_API_KEY}"
  }
}

If you use Docker Compose with dev containers, define the environment variables in the service definition and reference them from devcontainer.json.

Proxy and Certificate Gotchas

Aggregator endpoints typically use TLS. If your container lacks CA certificates, HTTPS requests will fail. Most base images include them, but minimal images (like Alpine) may not. Install ca-certificates if needed.

When behind a corporate proxy that performs TLS inspection, you may need to add the proxy's CA certificate to the container's trust store. Also, some proxies block CONNECT requests to non-standard ports; ensure the aggregator's port is allowed.

Testing Connectivity

Before running Claude Code, verify the container can reach the endpoint:

• Use curl -I https://api.your-aggregator.com to check DNS and TLS.
• Check environment variables with docker exec <container> env | grep ANTHROPIC.
• If using a proxy, test with curl -x http://proxy:port -I https://api.your-aggregator.com.

Security Considerations

Never commit API keys to version control. Use secrets management or environment variables. In Docker, prefer --env-file over -e to avoid leaking keys in process lists. In dev containers, use ${localEnv:...} to keep keys on the host.

Conclusion

Running Claude Code in containers against an aggregator endpoint is straightforward once you handle endpoint injection and networking. Pay attention to DNS, proxies, and certificate stores, and always keep your API key secure. With these steps, you can enjoy the benefits of containerization while using a single key to access multiple models through your aggregator.