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)

1. 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-"
   

2. Set environment variable:

   RECOMMENDED:

   export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-your-token-here
   

   ALTERNATE:

   # Copy .env.example to .env
   cp .env.example .env
   

   # Edit .env and update this line with your actual token
   CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-your-token-here
   

3. Start the containers:

   # Start containers (automatically uses .env file)
   docker compose up -d
   

4. Test it works:

   # TypeScript (using compose.yaml)
   docker compose exec typescript node /app/scripts/test-auth.js
   
   # Python (using compose-python.yaml)
   docker compose -f compose-python.yaml exec python python /app/scripts/test_auth.py
   

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:

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

License

MIT License - see LICENSE file for details