casjaysdevdocker/claude
1
0
Fork 0
mirror of https://github.com/casjaysdevdocker/claude synced 2026-06-24 14:01:02 -04:00
Code Issues Actions Packages Projects Releases Wiki Activity

🦈🏠🐜❗ Initial Commit ❗🐜🦈🏠

Browse Source
This commit is contained in:
Jason Hempstead
2026-01-22 13:19:16 -05:00
commit ee98df8672
46 changed files with 4768 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+516
View File
@@ -0,0 +1,516 @@
## 👋 Welcome to claude 🚀
Docker container for running Claude Code CLI with **full Docker-in-Docker support**.
This container provides a complete development environment with:
- **Persistent screen sessions** - Detach/reattach to Claude without losing context
- **Full Docker-in-Docker (DinD)** - Run Docker commands inside Claude Code
- **Claude Code CLI** with `--dangerously-skip-permissions` pre-configured
- **Persistent configuration** in `/config` - Settings and authentication
- **Persistent data** in `/data` - Logs, databases, caches (like `/var`)
- **Persistent workspace** in `/app` - Your project code
- **Multiple authentication methods** - Claude Pro subscription or API key
- **Pre-installed tools** - Docker, Docker Compose, containerd, git, curl, bash, screen
- **Native Claude Code installer** - Uses official installer (not deprecated npm package)
## Install my system scripts
```shell
sudo bash -c "$(curl -q -LSsf "https://github.com/systemmgr/installer/raw/main/install.sh")"
sudo systemmgr --config && sudo systemmgr install scripts
```
## Automatic install/update
```shell
dockermgr update claude
```
## Install and run container
### Prerequisites
- Docker installed with `--privileged` support
- Authentication via one of:
- **Claude Pro subscription** (recommended for Max users)
- **Anthropic API key** (pay-as-you-go)
### Authentication Options
Claude Code supports multiple authentication methods:
#### Option 1: Claude Pro Subscription (Recommended)
If you have a Claude Pro subscription with Claude.com:
- Claude Code will prompt you to authenticate interactively
- Supports Pro and Max tier subscriptions
- No additional API costs
- Just run the container and follow the prompts
- **Tip:** Mount `~/.claude` directory to preserve authentication across container restarts
#### Option 2: Anthropic API Key
For API-based usage with pay-as-you-go billing:
1. Go to [console.anthropic.com](https://console.anthropic.com)
2. Create an API key
3. Pass it via environment: `-e ANTHROPIC_API_KEY=sk-ant-api03-...`
**Note:** API keys and Claude Pro subscriptions are separate authentication methods. Use whichever fits your use case.
### Quick Start
**With Claude Pro Subscription:**
```shell
# Start container with Claude in persistent screen session
docker run -d \
--privileged \
--restart unless-stopped \
--name claude-code \
--hostname claude \
-e TZ=${TIMEZONE:-America/New_York} \
-e PUID=$(id -u) \
-e PGID=$(id -g) \
-v "$PWD:$PWD:z" \
-v "$HOME/.config/claude:/config:z" \
-v "$HOME/.local/share/claude:/data:z" \
-v "$HOME/.claude:/root/.claude:z" \
casjaysdevdocker/claude:latest
# Attach to Claude (automatically manages screen session)
docker exec -it claude-code claude
# Detach anytime with: Ctrl+A then D
# Reattach anytime with: docker exec -it claude-code claude
```
**With API Key:**
```shell
export ANTHROPIC_API_KEY="sk-ant-api03-your-key-here"
# Start container with Claude in persistent screen session
docker run -d \
--privileged \
--restart unless-stopped \
--name claude-code \
--hostname claude \
-e TZ=${TIMEZONE:-America/New_York} \
-e PUID=$(id -u) \
-e PGID=$(id -g) \
-e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
-v "$PWD:$PWD:z" \
-v "$HOME/.config/claude:/config:z" \
-v "$HOME/.local/share/claude:/data:z" \
-v "$HOME/.claude:/root/.claude:z" \
casjaysdevdocker/claude:latest
# Attach to Claude (automatically manages screen session)
docker exec -it claude-code claude
# Detach anytime with: Ctrl+A then D
# Reattach anytime with: docker exec -it claude-code claude
```
**Important notes:**
**File Permissions (PUID/PGID):**
- `-e PUID=$(id -u)` and `-e PGID=$(id -g)` set the user ID and group ID for file ownership
- When PUID/PGID are set (non-zero), the container creates a `claude` user with your UID/GID
- Files created in mounted directories (`/config`, `/data`, `$PWD`) will have **your ownership**, not root
- The container process runs as root, but files get your ownership through user mapping
- This prevents permission issues when editing files on the host
- **Optional:** Omit these (or set to 0) to run as root and have root-owned files
**Working Directory:**
- `-v "$PWD:$PWD:z"` mounts current directory to the **same path** inside container
- Paths in Claude's context **match your host** exactly
- No confusion about `/app` vs actual project location
**Credentials Mount:**
- `-v "$HOME/.claude:/root/.claude:z"` is optional but recommended
- **Mounts entire `.claude` directory**, not just the credentials file
- Avoids Docker creating directory when file doesn't exist
- Shares all Claude settings, not just authentication
- **Preserves authentication** across container recreations
- **Shares credentials** between native Claude Code and containerized version
- Only needed for Claude Pro subscription (not needed for API key)
### One-line attach command
```shell
# Start if not running, then attach to Claude
docker start claude-code 2>/dev/null || true && docker exec -it claude-code claude
```
### Pass additional arguments
```shell
# Pass custom arguments to Claude Code CLI
docker run -it --rm \
--privileged \
-e CLAUDE_ADDITIONAL_ARGS="--model opus-4" \
-v "$PWD:$PWD:z" \
-v "$HOME/.config/claude:/config:z" \
-v "$HOME/.local/share/claude:/data:z" \
casjaysdevdocker/claude:latest
```
## Persistent Sessions with Screen
Claude Code runs inside a **persistent `screen` session** by default. This allows you to:
- **Detach** from Claude without stopping it
- **Reattach** to your existing session anytime
- Keep your conversation history and context
- Run long tasks in the background
### Screen Session Management
Claude automatically runs in a persistent screen session. Simply run:
```bash
docker exec -it claude-code claude
```
This will:
- **Attach** to existing session if one exists
- **Create** a new session if none exists
No need to remember screen commands!
### Usage Examples
**Typical Workflow:**
```bash
# 1. Start container (first time only)
docker run -d --privileged --name claude-code \
-e PUID=$(id -u) -e PGID=$(id -g) \
-v "$PWD:$PWD:z" \
-v "$HOME/.config/claude:/config:z" \
-v "$HOME/.local/share/claude:/data:z" \
casjaysdevdocker/claude:latest
# 2. Attach to Claude (anytime)
docker exec -it claude-code claude
# 3. Work with Claude...
# 4. Detach (keeps running): Ctrl+A then D
# 5. Later, reattach
docker exec -it claude-code claude
```
**Fast attach/detach:**
1. While in Claude, press: `Ctrl+A` then `D` to detach
2. Claude continues running in the background
3. Run `docker exec -it claude-code claude` to reattach anytime
### Screen Quick Reference
| Action | Command |
| ---------------------------- | --------------------------------------------------------------------- |
| Attach to Claude | `docker exec -it claude-code claude` |
| Detach from session | `Ctrl+A` then `D` |
| List all sessions | `docker exec -it claude-code screen -ls` |
| Kill and restart session | `docker exec -it claude-code screen -X -S claude quit` |
| Create new window in session | `Ctrl+A` then `C` |
| Switch between windows | `Ctrl+A` then `N` (next) or `P` (previous) |
| Scroll in session | `Ctrl+A` then `Esc`, then arrow keys, press `Esc` to exit scroll mode |
## Full Docker-in-Docker Support
This container comes with **full Docker-in-Docker (DinD)** enabled by default:
- Complete Docker daemon runs inside the container
- Docker CLI, Docker Compose, and containerd included
- Requires `--privileged` flag
- Isolated Docker environment from host
- Can build images, run containers, use docker-compose
**Claude Code can execute Docker commands:**
```bash
docker ps
docker build -t myapp .
docker-compose up -d
docker run --rm alpine echo "Hello from nested container"
```
**Note:** Always use `--privileged` flag for full Docker support.
## via docker-compose
**With Claude Pro Subscription:**
```yaml
version: "3.8"
services:
claude-code:
image: casjaysdevdocker/claude:latest
container_name: claude-code
hostname: claude
privileged: true
stdin_open: true
tty: true
environment:
- TZ=America/New_York
- PUID=${UID:-1000}
- PGID=${GID:-1000}
- CLAUDE_ADDITIONAL_ARGS=
volumes:
- "./:${PWD}:z"
- "${HOME}/.config/claude:/config:z"
- "${HOME}/.local/share/claude:/data:z"
- "${HOME}/.claude:/root/.claude:z"
restart: unless-stopped
```
**With API Key:**
```yaml
version: "3.8"
services:
claude-code:
image: casjaysdevdocker/claude:latest
container_name: claude-code
hostname: claude
privileged: true
stdin_open: true
tty: true
environment:
- TZ=America/New_York
- PUID=${UID:-1000}
- PGID=${GID:-1000}
- ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
- CLAUDE_ADDITIONAL_ARGS=
volumes:
- "./:${PWD}:z"
- "${HOME}/.config/claude:/config:z"
- "${HOME}/.local/share/claude:/data:z"
- "${HOME}/.claude:/root/.claude:z"
restart: unless-stopped
```
Save as `docker-compose.yml` and run:
```shell
# With Claude Pro - no API key needed
docker-compose up -d
docker-compose exec claude-code claude
# With API key
export ANTHROPIC_API_KEY="sk-ant-api03-..."
docker-compose up -d
docker-compose exec claude-code claude
```
## Configuration
### Environment Variables
**Authentication:**
- `ANTHROPIC_API_KEY` (optional): Your Anthropic API key
- Not required if using Claude Pro subscription with credentials file
- Use either API key OR credentials file, not both
**User Permissions:**
- `PUID` (recommended): User ID for file ownership (default: 0/root)
- Use `$(id -u)` to match your host user
- **Controls file ownership** on mounted volumes (`/config`, `/data`, `$PWD`)
- When non-zero, creates a `claude` user inside container with your UID
- Container process runs as root, files created get mapped to your UID through `chown`
- If set to 0 or omitted, files are owned by root (no user mapping)
- `PGID` (recommended): Group ID for file ownership (default: 0/root)
- Use `$(id -g)` to match your host group
- When non-zero, creates a `claude` group inside container with your GID
- Prevents permission issues when editing files on the host
- If set to 0 or omitted, files are owned by root group (no group mapping)
**General:**
- `TZ` (optional): Timezone (default: America/New_York)
- `CLAUDE_ADDITIONAL_ARGS` (optional): Additional arguments to pass to Claude Code CLI
- `CLAUDE_CONFIG_DIR` (optional): Config directory path (default: /config/claude)
- `CLAUDE_WORK_DIR` (optional): Working directory path (default: current PWD)
### Settings File
The container uses a persistent settings file located at `/config/claude/settings.json`.
On first run, it will be initialized with a default configuration that includes:
- Permissions for common operations (Read, Write, WebSearch, Bash commands)
- `--dangerously-skip-permissions` flag enabled by default
- Pre-configured hooks for file operations
- Thinking mode set to "off"
- Auto-commit disabled
You can modify this file to customize Claude Code's behavior. The file persists between container restarts.
### Volume Mounts
**Required volumes:**
- `/config` - Configuration directory (contains settings.json)
- `/data` - Application data directory (logs, databases, caches, Docker volumes, etc.)
- `$PWD:$PWD` - **Current directory mounted to same path** inside container
- Paths in Claude's context match your host exactly
- No path translation needed
- Files created have your user ownership (when using PUID/PGID)
**Optional but recommended:**
- `~/.claude` → `/root/.claude` - Claude Pro authentication and settings
- **Preserves authentication** across container recreations
- **Shares credentials** with native Claude Code installation (`.credentials.json`)
- **Shares all Claude settings** between host and container
- **Only needed for Claude Pro** (not required if using API key)
- Directory and files created automatically on first authentication
- **Better than mounting just the file** - avoids Docker creating directory when file doesn't exist
**Understanding the directory structure:**
- `$PWD:$PWD` - Your project source code (transparent path mapping)
- `/config` - Container configuration and Claude settings
- `/data` - Runtime data (databases, logs, docker volumes, temp files, caches)
- Example: `/data/logs` - Application and Docker daemon logs
- Example: `/data/postgres` - PostgreSQL data
- Example: `/data/mysql` - MySQL data
- Example: `/data/redis` - Redis persistence
- Similar to `/var` on traditional Linux systems
### Docker-in-Docker Details
This container runs a **full Docker daemon** by default:
- Docker CLI, Docker Compose, containerd pre-installed
- Isolated Docker environment (separate from host)
- Can build images, run containers, use docker-compose
- Requires `--privileged` flag
- Uses VFS storage driver for compatibility
- Docker daemon starts automatically on container startup
## Get source files
```shell
dockermgr download src casjaysdevdocker/claude
```
OR
```shell
git clone "https://github.com/casjaysdevdocker/claude" "$HOME/Projects/github/casjaysdevdocker/claude"
```
## Build container
```shell
cd "$HOME/Projects/github/casjaysdevdocker/claude"
buildx
```
## Quick Reference
### Start Container (First Time)
```bash
# Claude Pro users
docker run -d --privileged --restart unless-stopped --name claude-code \
-e PUID=$(id -u) -e PGID=$(id -g) \
-v "$HOME/.config/claude:/config:z" \
-v "$HOME/.local/share/claude:/data:z" \
-v "$PWD:$PWD:z" \
-v "$HOME/.claude:/root/.claude:z" \
casjaysdevdocker/claude:latest
# API Key users
export ANTHROPIC_API_KEY="sk-ant-api03-..."
docker run -d --privileged --restart unless-stopped --name claude-code \
-e PUID=$(id -u) -e PGID=$(id -g) \
-e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
-v "$HOME/.config/claude:/config:z" \
-v "$HOME/.local/share/claude:/data:z" \
-v "$PWD:$PWD:z" \
-v "$HOME/.claude:/root/.claude:z" \
casjaysdevdocker/claude:latest
```
### Daily Usage
```bash
# Attach to Claude (creates or attaches to screen session)
docker exec -it claude-code claude
# Detach: Ctrl+A then D
# One-liner to start container and attach
docker start claude-code 2>/dev/null || true && docker exec -it claude-code claude
```
## Troubleshooting
### "Cannot start Docker-in-Docker daemon - insufficient privileges"
- **Solution:** Add `--privileged` flag to your docker run command
- This container requires privileged mode for full Docker-in-Docker support
### Authentication prompts
- **Claude Pro users:** Follow the interactive prompts to authenticate
- **API users:** Set `ANTHROPIC_API_KEY` environment variable
### Credentials file issues
**Problem:** Authentication not persisting across container restarts
**Solution:** Mount the entire `~/.claude` directory, not just the file:
```bash
# ✅ Correct - mount directory
-v "$HOME/.claude:/root/.claude:z"
# ❌ Wrong - Docker creates directory if file doesn't exist
-v "$HOME/.claude/.credentials.json:/root/.claude/.credentials.json:z"
```
**Why:** If the file doesn't exist on host, Docker creates it as a **directory** instead, breaking authentication.
### Docker commands not working inside container
- Ensure you're using `--privileged` flag
- Wait a few seconds for Docker daemon to initialize
- Check logs: `docker logs claude-code`
### Screen session issues
```bash
# Just run claude - it will create a session if needed
docker exec -it claude-code claude
# List all screen sessions (advanced)
docker exec -it claude-code screen -ls
# Force kill screen session and create new one
docker exec -it claude-code screen -X -S claude quit
docker exec -it claude-code claude
# Manually restart the init script (if needed)
docker exec -it claude-code /usr/local/etc/docker/init.d/99-claude.sh
```
## Authors
🤖 casjay: [Github](https://github.com/casjay) 🤖
⛵ casjaysdevdocker: [Github](https://github.com/casjaysdevdocker) [Docker](https://hub.docker.com/u/casjaysdevdocker) ⛵