create-claude-docker

create-claude-docker

Create Docker-based Claude Code development environment with Z.AI GLM-4.7 support.

Features

• 🐳 Docker-based: Isolated environment for each project
• 🔑 Auto-configured: API key injection on container start
• 🤖 Z.AI GLM-4.7: Pre-configured for Z.AI's Claude-compatible models
• 👤 Non-root user: Supports --dangerously-skip-permissions flag
• 🛠️ Default agents: Pre-configured specialized agents (backend, frontend, debugging, etc.)

Quick Start

Create a new project with npx

# Interactive mode
npx create-claude-docker my-project

# With options
npx create-claude-docker my-project --description "My AI project" --author "Your Name"

CLI Options

Option	Alias	Description
--description	-d	Project description
--author	-a	Author name

After creation

cd my-project

# Add your Z.AI API key
nano .env

# Build and start
npm run docker:build
npm run docker:up

# Run Claude Code
npm run claude:unsafe

Manual Setup (Alternative)

Option 2: Using Z.AI GLM-4.7 Models

Z.AI provides GLM-4.7 models that are compatible with Claude Code through an Anthropic-compatible API endpoint.

• Get Z.AI API key:

  • Visit: https://z.ai/manage-apikey/apikey-list
  • Or: https://open.bigmodel.cn/
  • Sign up and get your API key

• Configure environment:

  cp .env.example .env
  # Edit .env and set your Z.AI API key:
  ZAI_API_KEY=your-zai-api-key-here
  

• Build and start:

  npm run docker:build
  npm run docker:up
  

  The container will automatically configure Claude Code with your API key on startup. You should see:

  🚀 Starting Claude Code container...
  🔧 Configuring Claude Code settings...
  ✅ Claude Code configured with Z.AI API key
  📋 Current settings.json:
  ...
  

• Run Claude Code:

  npm run claude:unsafe
  

• Verify configuration: Once inside Claude Code, run /status to check the current model in use. You should see glm-4.7 as the active model.

Switching Between Models

To switch from GLM-4.7 back to Anthropic Claude:

• Edit .env and set ANTHROPIC_API_KEY to your Anthropic key
• Remove or edit .claude/settings.json to remove the GLM model configuration
• Restart the container:

  npm run docker:down
  npm run docker:up
  

To customize model selection:

Edit ./claude-data/settings.json (created on first run) or .claude/settings.json:

{
  "env": {
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-3-5-haiku-20241022",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-3-5-sonnet-20241022",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-3-5-sonnet-20241022"
  }
}

Available Commands

Command	Description
npm run docker:build	Build Docker image
npm run docker:up	Start container in background
npm run docker:down	Stop and remove container
npm run docker:logs	View container logs
npm run docker:shell	Open bash shell in container
npm run claude	Run Claude Code (normal mode)
npm run claude:unsafe	Run Claude Code with --dangerously-skip-permissions

Project Structure

.
├── .docker/
│   └── Dockerfile          # Docker image definition
├── .claude/
│   ├── settings.json       # Default GLM-4.7 model configuration
│   └── agents/             # Default agent configurations
│       ├── backend-node-pro.md
│       ├── ui-architect.md
│       ├── debugging-expert.md
│       ├── architecture-reviewer.md
│       └── technical-writer.md
├── .env.example            # Environment variables template
├── docker-compose.yml      # Docker Compose configuration
├── package.json            # NPM scripts
├── claude-data/            # Claude Code config (auto-created, overrides .claude/)
└── README.md               # This file

Default Agents

The boilerplate includes pre-configured specialized agents:

Agent	Purpose	Model
backend-node-pro	Backend Node.js development (API clients, workers, Firebase)	Opus/GLM-4.7
ui-architect	Frontend/React design (components, styling, UX)	Opus/GLM-4.7
debugging-expert	Debugging complex issues and root cause analysis	Opus/GLM-4.7
architecture-reviewer	System design evaluation and architectural decisions	Sonnet/GLM-4.7
technical-writer	Documentation, API references, guides	Sonnet/GLM-4.7

Configuration

Non-Root User

The container runs as user claude (UID 2000) to satisfy Claude Code's security requirements when using --dangerously-skip-permissions.

Environment Variables

Create a .env file from .env.example:

# Option 1: Anthropic Claude
ANTHROPIC_API_KEY=sk-ant-xxxxx

# Option 2: Z.AI GLM-4.7 (uses ZAI_API_KEY, overrides ANTHROPIC_API_KEY)
ZAI_API_KEY=your-zai-api-key-here

Default Configuration

The API key is injected directly as an environment variable (ANTHROPIC_AUTH_TOKEN) in docker-compose.yml.

• API key injection: The docker-compose.yml passes ANTHROPIC_AUTH_TOKEN from your .env (supports both ZAI_API_KEY and ANTHROPIC_API_KEY)
• Why env var? Settings from settings.json may be mounted over by the claude-data volume before the entrypoint can write them. Using direct env vars ensures the API key is always available.
• Model configuration: Model mappings and base URL are stored in .claude/settings.json
• Agents: Pre-defined agent configurations from .claude/agents/ are available immediately
• Persistence: Claude Code state is stored in ./claude-data/ volume (gitignored)

Git Integration

Your host's .gitconfig is mounted read-only at /home/claude/.gitconfig, so commits in the container will be signed with your credentials.

Manual Docker Commands

If you prefer running Docker commands directly:

# Build and start
docker compose up -d --build

# Enter container
docker compose exec claude bash

# Run claude directly
docker compose exec claude claude --dangerously-skip-permissions

# Stop
docker compose down

Tips

• First setup: Run npm run docker:build && npm run docker:up before first use
• Persistent config: Claude Code settings stored in ./claude-data/ (gitignore this)
• Shared gitconfig: Commits use your host's git identity
• Workspace: Project mounted at /workspace in container
• GLM-4.7 users: The default settings.json is pre-configured for GLM-4.7. Just set your Z.AI API key in .env
• Reset config: Delete ./claude-data/ and restart to revert to default configuration
• Custom agents: Add new .md files to .claude/agents/ or ./claude-data/agents/ before building

Multi-line Prompts in Docker Container

The /terminal-setup command doesn't work in Docker containers (detected as xterm). Use these alternatives:

Method	How to use
Ctrl+J	Press Ctrl+J to insert a new line (recommended)
Backslash	Type \ before pressing Enter to continue on next line

Example with backslash:

> This is line one\
  and this continues on line two\
  and line three

Troubleshooting

GLM-4.7 Configuration Not Working

• Check API key: Ensure ZAI_API_KEY or ANTHROPIC_API_KEY is set in your .env file
• Check container logs to verify settings were generated:

  npm run docker:logs
  # Should show: ✅ Claude Code configured with Z.AI API key
  

• Verify settings.json: Run /status in Claude Code to see current model
• Debug inside container:

  npm run docker:shell
  cat ~/.claude/settings.json
  

• Rebuild and restart (if API key changed):

  npm run docker:down
  npm run docker:up
  

Permission Denied Errors

The container runs as non-root user claude (UID 2000). If you encounter permission issues:

• Check file ownership: Ensure your project files are accessible by UID 2000
• Adjust UID: Modify the UID in Dockerfile if needed (currently 2000)

Project Structure

create-claude-docker/
├── bin/
│   └── create.js           # CLI entry point
├── template/               # Boilerplate files copied to new projects
│   ├── .docker/
│   │   ├── Dockerfile
│   │   └── entrypoint.sh
│   ├── .claude/
│   │   ├── settings.json
│   │   └── agents/
│   ├── .env.example
│   ├── .gitignore
│   ├── docker-compose.yml
│   └── README.md
├── package.json
└── README.md

Publishing to npm

To publish this package to npm:

# Login to npm
npm login

# Update version
npm version patch  # or minor, major

# Publish
npm publish

After publishing, users can create new projects with:

npx create-claude-docker my-awesome-project

Development

To test the CLI locally:

# From the repository root
node bin/create.js test-project

# Or link globally
npm link
create-claude-docker test-project

License

MIT