Claude Agent SDKs in Docker

Docker images with Official Claude Agent SDK built-in.

Images:

TypeScript (607MB) - Includes the @anthropic-ai/claude-agent-sdk SDK and @anthropic-ai/claude-code CLI.
🐍 Python (693MB) - adds Python 3 and Anthropic's claude-agent-sdk-python aka claude-agent-sdk on PyPI.
🏔️ Alpine TypeScript (383MB) - Minimal Alpine Linux base
🏔️ Alpine Python (474MB) - Alpine with Python support

Why use these images?

✅ Works non-interactively out of the box

The Claude CLI normally requires an interactive OAuth flow and onboarding wizard on first run — not ideal inside a container. These images come pre-configured to skip all interactive prompts. Just pass your token as an env var and go.

Generate a token on your host machine with claude setup-token, then pass it to the container via CLAUDE_CODE_OAUTH_TOKEN.

Available Images

Debian-based:

ghcr.io/cabinlab/claude-agent-sdk:typescript - CLI + TypeScript SDK
ghcr.io/cabinlab/claude-agent-sdk:python - Above + Python SDK

Alpine-based:

ghcr.io/cabinlab/claude-agent-sdk:alpine - Minimal TypeScript
ghcr.io/cabinlab/claude-agent-sdk:alpine-python - Minimal + Python

Quick Start (for Claude Pro and Max users)

Get your OAuth token (on host machine):

claude setup-token

# Follow Anthropic's 2 or 3 screens of auth flow CLI --> Browser --> CLI

# Copy the token that starts with "sk-ant-oat01-"

Set environment variable:

Using Docker Compose (Full Examples)

Note: This project includes compose files for different variants:

compose.yaml - Debian TypeScript
compose-python.yaml - Debian Python
compose-alpine.yaml - Alpine TypeScript
compose-alpine-python.yaml - Alpine Python

Option 1: Run TypeScript

# Start TypeScript container
docker compose up -d

# Run TypeScript example
docker compose exec typescript tsx /app/examples/typescript/hello.ts

# Interactive TypeScript development
docker compose exec typescript bash

Option 2: Run Python (Includes Typescript!)

# Start Python container
docker compose -f compose-python.yaml up -d

# Run Python example
docker compose -f compose-python.yaml exec python python /app/examples/python/hello.py

# Interactive Python development
docker compose -f compose-python.yaml exec python python

# Tip: If you only use Python, rename the file for convenience
mv compose-python.yaml compose.yaml

Using Docker Run

For users who prefer direct docker commands:

# TypeScript
docker run --rm -it \
  -e CLAUDE_CODE_OAUTH_TOKEN="sk-ant-oat01-..." \
  -v $(pwd):/app \
  -p 3000:3000 \
  ghcr.io/cabinlab/claude-agent-sdk:typescript \
  bash

# Python
docker run --rm -it \
  -e CLAUDE_CODE_OAUTH_TOKEN="sk-ant-oat01-..." \
  -v $(pwd):/app \
  -p 3000:3000 \
  ghcr.io/cabinlab/claude-agent-sdk:python \
  python

Features

Included Tools

Base (CLI + Typescript SDK)

Non-root user - Security best practice
Claude Agent SDK CLI - Familiar Claude CLI and auth flow
TypeScript SDK - Native TypeScript/JavaScript support
tsx - Run TypeScript files directly without compilation
Git, cURL, jq - Essential development tools

Python

Python SDK - Python bindings (in :python image)

Claude Config Scaffolding

Each container includes a .claude/ directory with:

Slash Commands - Directory and instructions for extending Claude with custom commands
Hooks - Directory and instructions to leverage Claude's behavior
Example configurations and documentation

Mount your own configuration:

docker run -v ~/.claude:/home/claude/.claude ...

Authentication

Which method should I use?

Claude Pro/Max users

Long-lived tokens [Recommended] → See Quick Start above
Session based tokens - This is the standard Claude auth flow

Anthropic API Keys

Anthropic API keys → Set ANTHROPIC_API_KEY in your .env file
Can also be used through standard Claude auth flow
⚠️ Likely overrides OAuth/Subscription plan settings
✅ Use API OR Subscription, not both together

For technical details and troubleshooting, see our Authentication Guide.

Building Your Own Images

Extending the Base Images (click to expand)

For TypeScript Projects

# For TypeScript projects
FROM ghcr.io/cabinlab/claude-agent-sdk:typescript

WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
CMD ["npm", "start"]

For Python Projects

# For Python projects
FROM ghcr.io/cabinlab/claude-agent-sdk:python

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "main.py"]

Building Locally

# Build TypeScript base
docker build -f Dockerfile.typescript -t claude-agent-sdk:typescript .

# Build Python extension
docker build --build-arg BASE_IMAGE=claude-agent-sdk:typescript \
  -t claude-agent-sdk:python .

Security

Containers run as non-root user claude
OAuth tokens should never be built into images
Use .aiexclude to prevent Claude from accessing sensitive files
Mount secrets at runtime, don't embed them

Examples

See the examples/ directory for sample code in:

JavaScript
TypeScript (with direct execution via tsx)
Python

Automatic Updates

This repository automatically checks for new SDK versions daily and creates pull requests when updates are available. The automated workflow:

Runs daily at 2 AM UTC
Checks npm for Claude Agent SDK CLI updates
Checks PyPI for Python SDK updates
Creates PRs with updated versions
Auto-merges PRs after tests pass

Manual version checks can be triggered via the "Check for Updates" workflow in the Actions tab.

Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Submit a pull request

License

MIT License - see LICENSE file for details

claude-code-sdk-docker