There is nothing exotic about putting the Claude SDK in a container. The Python package installs with pip install anthropic (Python 3.9+), the TypeScript package with npm install @anthropic-ai/sdk (Node.js 20 LTS+), and neither needs system libraries beyond a normal language base image. The design work is all about credentials and image hygiene.
The one hard rule: no secrets in the image
Anything present during docker build can end up baked into an image layer — an ENV ANTHROPIC_API_KEY=... line, a copied .env file, even a build argument that a later instruction echoes. Images get pushed to registries, pulled to laptops, and cached on build hosts; a credential in a layer is a credential you no longer control. Anthropic's guidance for API keys — store in a secrets manager, rotate periodically, revoke on leak — is incompatible with a key frozen into an artifact.
The correct flow uses the SDK's own behavior: per the authentication docs, the clients automatically read ANTHROPIC_API_KEY from the environment. So the image contains only code, and the orchestrator supplies the variable when the container starts — a Kubernetes Secret mounted as an env var, an ECS task definition referencing AWS Secrets Manager, a docker run -e in development. Add .env to both .gitignore and .dockerignore so a local convenience file can't leak into the build context.
from anthropic import Anthropic
# Fail fast at startup if the runtime forgot to inject credentials,
# instead of failing on the first user request minutes later.
import os
if not os.environ.get("ANTHROPIC_API_KEY"):
raise RuntimeError("ANTHROPIC_API_KEY not set — check the pod/task secret")
client = Anthropic()
Better than an injected key: identity-based auth
For production containers, Anthropic recommends Workload Identity Federation over static keys: the workload exchanges its platform-issued identity token for a short-lived Claude API access token, which the SDK refreshes automatically. Kubernetes service accounts are listed among compatible issuers, so a pod can authenticate to the first-party API with no long-lived secret mounted anywhere.
On the third-party platforms, the same idea comes free with the cloud. Amazon Bedrock (AnthropicBedrockMantle) and Claude Platform on AWS (AnthropicAWS) authenticate through the AWS default credential provider chain, which includes ECS container credentials and EC2 instance metadata — meaning a task role or instance role signs requests and your container holds nothing. Vertex AI (AnthropicVertex) works the same way through Google's Application Default Credentials. Remember that AnthropicAWS also requires AWS_REGION and ANTHROPIC_AWS_WORKSPACE_ID to be set, and raises at construction if either is missing — another reason the fail-fast startup check above is worth having.
Multi-stage builds: small, boring, reproducible
A multi-stage Dockerfile separates the environment that builds your app from the image that runs it. The builder stage installs compilers, dev dependencies, and lockfile tooling; the final stage starts from a slim base image and copies in only the installed packages and your source. For Claude SDK apps the benefits are the usual ones — smaller attack surface, faster pulls, no build tooling in production — plus one credential-specific bonus: if any build step ever needed a secret (a private package index, for example), it stays in the discarded builder stage rather than the shipped image. Use BuildKit secret mounts for build-time secrets rather than build args, which persist in image metadata.
pip install anthropic in a Dockerfile means two builds a week apart may ship different SDK versions — see pinning SDK versions.Runtime configuration beyond the key
Keep model choice, max_tokens defaults, and platform selection in environment variables too, following twelve-factor practice — the same image should serve staging (perhaps pointed at Haiku 4.5 for cost) and production without a rebuild. If you run against multiple platforms for failover, environment-driven client selection keeps that logic in one place; SDK environment configuration covers the variables each client honors.
Where to go next
Wire the built image into CI with the GitHub Actions guide, and plan how the injected key gets rotated in rotating API keys without downtime. For fetching secrets from a manager inside application code, see secrets handling patterns.