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.

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

2. Configure environment:

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

3. 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:
   ...

4. Run Claude Code:

   npm run claude:unsafe

5. 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:

1. Edit .env and set ANTHROPIC_API_KEY to your Anthropic key
2. Remove or edit .claude/settings.json to remove the GLM model configuration
3. 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

1. First setup: Run npm run docker:build && npm run docker:up before first use
2. Persistent config: Claude Code settings stored in ./claude-data/ (gitignore this)
3. Shared gitconfig: Commits use your host's git identity
4. Workspace: Project mounted at /workspace in container
5. GLM-4.7 users: The default settings.json is pre-configured for GLM-4.7. Just set your Z.AI API key in .env
6. Reset config: Delete ./claude-data/ and restart to revert to default configuration
7. 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

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

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

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

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

5. 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:

1. Check file ownership: Ensure your project files are accessible by UID 2000
2. 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