https://github.com/cabinlab/claude-code-sdk-docker
Docker containers for Claude Code Typescript and Python SDKs with built-in authentication support for Claude Pro and Max plans
https://github.com/cabinlab/claude-code-sdk-docker
claude-code claude-code-sdk docker-container
Last synced: 4 days ago
JSON representation
Docker containers for Claude Code Typescript and Python SDKs with built-in authentication support for Claude Pro and Max plans
- Host: GitHub
- URL: https://github.com/cabinlab/claude-code-sdk-docker
- Owner: cabinlab
- License: mit
- Created: 2025-07-17T03:08:09.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-08-04T02:07:36.000Z (7 months ago)
- Last Synced: 2026-01-28T07:42:51.592Z (20 days ago)
- Topics: claude-code, claude-code-sdk, docker-container
- Language: Shell
- Homepage:
- Size: 72.3 KB
- Stars: 21
- Watchers: 0
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Claude Agent SDKs in Docker
[](https://discord.gg/aaSgZBgkCK) [](https://github.com/cabinlab/claude-code-sdk-docker/actions/workflows/build-and-publish.yml)
### Docker images with Official Claude Agent SDK built-in.
Images:
- TypeScript (607MB) - Includes the [@anthropic-ai/claude-agent-sdk](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) SDK and [@anthropic-ai/claude-code](https://www.npmjs.com/package/@anthropic-ai/claude-code) CLI.
- 🐍 Python (693MB) - adds Python 3 and Anthropic's [claude-agent-sdk-python](https://github.com/anthropics/claude-agent-sdk-python) aka [claude-agent-sdk](https://pypi.org/project/claude-agent-sdk/) on PyPI.
- 🏔️ Alpine TypeScript (383MB) - Minimal Alpine Linux base
- 🏔️ Alpine Python (474MB) - Alpine with Python support
## Why use these images?
### ✅ Claude Pro and Max subscription compatibility
***Problem:*** The Claude Agent SDKs use the CLI OAuth flow, which is clunky inside a container.
***Solution:*** These containers replace the CLI authentication with Long-lived access tokens. See: `claude setup-token --help`
## 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):
```bash
claude setup-token
```
```bash
# Follow Anthropic's 2 or 3 screens of auth flow CLI --> Browser --> CLI
```
```bash
# Copy the token that starts with "sk-ant-oat01-"
```
2. **Set environment variable**:
#### RECOMMENDED:
```bash
export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-your-token-here
```
ALTERNATE:
```bash
# Copy .env.example to .env
cp .env.example .env
```
```bash
# Edit .env and update this line with your actual token
CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-your-token-here
```
3. **Start the containers**:
```bash
# Start containers (automatically uses .env file)
docker compose up -d
```
4. **Test it works**:
```bash
# 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
```bash
# 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!)
```bash
# 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:
```bash
# 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:
```bash
docker run -v ~/.claude:/home/claude/.claude ...
```
## Authentication
### Which method should I use?
#### Claude Pro/Max users
- Long-lived tokens [Recommended] → See [Quick Start](#quick-start-for-claude-pro-and-max-users) 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](docs/AUTHENTICATION.md).
## Building Your Own Images
Extending the Base Images (click to expand)
### For TypeScript Projects
```dockerfile
# 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
```dockerfile
# 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
```bash
# 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