One command. Full AI development workstation. Claude Code, web UI, headless browser, 7 AI CLIs, 50+ dev tools — containerized and ready.

You were going to spend 2 hours setting this up manually. Or you could just docker compose up.

Works with your existing Claude Code subscription. Max/Pro plan, API key — whatever you have, it just works.

You know the drill. You want Claude Code. But you also want it in a browser. With a headless browser for screenshots and testing. With Playwright configured. With every AI CLI. With TypeScript, Python, deployment tools, database clients, GitHub CLI.

So you start installing things. One by one. Then Chromium won't launch because Docker's shared memory is 64MB. Then Xvfb isn't configured. Then the UID inside the container doesn't match your host and everything is permission denied. Then you realize Claude Code's installer hangs when WORKDIR is root-owned. Then SQLite locks on your NAS mount. Then—

HolyClaude is the container I built after solving every single one of those problems.

I've been running this daily on my own server for weeks. Every bug has been hit, diagnosed, and fixed. Every edge case has been handled. Every "why doesn't this work in Docker" has been answered.

You pull it. You run it. You open your browser. You build.

This runs the real Claude Code CLI. Not a wrapper. Not a proxy. Not a knock-off.

Your existing Anthropic account works directly:

• Claude Max/Pro plan — authenticate through the web UI (OAuth), same as desktop Claude Code
• Anthropic API key — set it through the web UI, same billing as always
• No extra cost — HolyClaude is free and open source. You only pay Anthropic for what you use, like you already do.

HolyClaude doesn't touch your credentials. They're stored locally in your bind-mounted volume (./data/claude/), same as they would be on bare metal.

↑ back to top

↑ back to top

1. Create a folder for HolyClaude:

mkdir holyclaude && cd holyclaude

2. Create a docker-compose.yaml file. Copy one of the templates below:

• Quick template — minimal, zero config, just works
• Full template — all options, fully documented

3. Pull and start:

docker compose up -d

4. Open the web UI:

http://localhost:3001

5. Create a CloudCLI account (takes 10 seconds), sign in with your Anthropic account, and you're live.

No .env files. No pre-configuration. No reading 40 pages of docs before you can start. It just runs.

↑ back to top

↑ back to top

I built this because I was tired of re-doing the same setup every time. Installing Claude Code, wiring up a web UI, configuring Chromium in Docker, fixing permission issues, debugging process supervision. Every time.

So I made a container that does all of it. And then I hit every possible bug so you don't have to.

The last row of every manual setup is "works on my machine." HolyClaude works on every machine.

↑ back to top

HolyClaude runs the official Claude Code CLI from Anthropic. Your existing account works out of the box.

HolyClaude is free and open source. You only pay your AI providers for usage, same as you already do. We don't proxy, intercept, or touch your credentials. They live in your local bind mount.

↑ back to top

Two flavors. Same quality. Pick your weight class.

# Full — batteries included (recommended)
docker pull coderluii/holyclaude

# Slim — lean and mean
docker pull coderluii/holyclaude:slim

latest is always the full image. Slim users: don't worry — when you ask Claude to do something that needs a missing tool, it installs it in seconds. You get the same capabilities, just with a smaller initial download.

↑ back to top

The "I just want it running" template. Copy this entire block into a docker-compose.yaml file:

# ==============================================================================
# HolyClaude — Quick Start
# Just run: docker compose up -d
# Then open: http://localhost:3001
# ==============================================================================

services:
  holyclaude:
    image: coderluii/holyclaude:latest     # Full image (use :slim for smaller download)
    container_name: holyclaude
    hostname: holyclaude
    restart: unless-stopped
    shm_size: 2g                           # Chromium needs this — don't remove
    network_mode: bridge
    cap_add:
      - SYS_ADMIN                          # Required: Chromium sandboxing
      - SYS_PTRACE                         # Required: debugging tools
    security_opt:
      - seccomp=unconfined                 # Required: Chromium in Docker
    ports:
      - "3001:3001"                        # CloudCLI web UI
    volumes:
      #
      # ./data/claude — Your settings, credentials, API keys, and Claude's memory.
      #                  This is what survives container rebuilds.
      #                  NEVER delete this folder — your auth lives here.
      #
      - ./data/claude:/home/claude/.claude
      #
      # ./workspace — Your code. All projects go here.
      #               Bind-mounted so you can access files from your host.
      #
      - ./workspace:/workspace
    environment:
      - TZ=UTC                             # Your timezone (e.g., America/New_York, Europe/London)

Then:

docker compose up -d

Open http://localhost:3001. Create a CloudCLI account. Sign in with your Anthropic account. Build something.

That's the whole setup. You're done.

Why SYS_ADMIN + seccomp=unconfined? Chromium needs these to run inside Docker — it's standard for any containerized browser (Playwright docs, Puppeteer docs, every CI pipeline that runs browser tests). Without them, Chromium crashes on startup. This is not a security risk unique to HolyClaude.

Why shm_size: 2g? Docker gives containers 64MB of shared memory by default. Chromium uses /dev/shm heavily for tab rendering. At 64MB, tabs crash randomly. 2GB is the recommended minimum for any Chromium-in-Docker setup.

↑ back to top

Same image, every knob exposed. Copy this entire block into a docker-compose.yaml file:

# ==============================================================================
# HolyClaude — Full Configuration
# All options documented inline.
# Detailed docs: https://github.com/CoderLuii/HolyClaude/blob/main/docs/configuration.md
# ==============================================================================

services:
  holyclaude:
    image: coderluii/holyclaude:latest     # Full image (use :slim for smaller download)
    container_name: holyclaude
    hostname: holyclaude
    restart: unless-stopped
    shm_size: 2g                           # Chromium shared memory — increase to 4g for heavy browser use
    network_mode: bridge
    cap_add:
      - SYS_ADMIN                          # Required: Chromium sandboxing
      - SYS_PTRACE                         # Required: debugging tools (strace, lsof)
    security_opt:
      - seccomp=unconfined                 # Required: Chromium syscall requirements
    ports:
      #
      # CloudCLI web UI — this is the only port you need.
      # Override the host-side port from `.env` if 3001 is already in use.
      #
      - "${HOLYCLAUDE_HOST_PORT:-3001}:3001"
      #
      # Dev server ports — uncomment as needed.
      # These let you access dev servers running inside the container from your host browser.
      #
      # - "3000:3000"                      # Next.js / Express
      # - "4321:4321"                      # Astro
      # - "5173:5173"                      # Vite
      # - "8787:8787"                      # Wrangler (Cloudflare Workers)
      # - "9229:9229"                      # Node.js debugger
    volumes:
      #
      # PERSISTENT DATA
      #
      # ./data/claude — Settings, credentials, API keys, Claude's memory file.
      #                  Survives container rebuilds. NEVER delete this folder.
      #                  Override the host path from `.env` if you want it elsewhere.
      #
      - ${HOLYCLAUDE_HOST_CLAUDE_DIR:-./data/claude}:/home/claude/.claude
      #
      # ./workspace — Your code and projects. Everything you build goes here.
      #               Accessible from your host machine.
      #               Override the host path from `.env` if you want a different root.
      #
      - ${HOLYCLAUDE_HOST_WORKSPACE_DIR:-./workspace}:/workspace
    environment:
      #
      # TIMEZONE
      # Full list: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
      #
      - TZ=UTC
      #
      # PERFORMANCE
      # Node.js heap memory limit in MB. Increase if you work on large monorepos
      # and hit out-of-memory errors. 4096 (4GB) is a solid default.
      #
      - NODE_OPTIONS=--max-old-space-size=4096
      #
      # USER MAPPING
      # Match these to your host user so files created inside the container
      # have the right ownership on your host. Run `id -u` and `id -g` on your host.
      #
      - PUID=1000
      - PGID=1000
      #
      # SMB/CIFS NETWORK MOUNTS
      # Only enable these if your volumes are on a NAS, Samba share, or CIFS mount.
      # They enable polling-based file watching since network mounts don't support inotify.
      # Leave commented out for local storage — polling uses more CPU.
      #
      # - CHOKIDAR_USEPOLLING=1
      # - WATCHFILES_FORCE_POLLING=true
      #
      # NOTIFICATIONS (optional)
      # Get notified when Claude finishes a task or hits an error.
      # Uses Apprise — supports 100+ services. Also requires creating a flag file
      # inside the container: touch ~/.claude/notify-on
      #
      # - NOTIFY_DISCORD=discord://webhook_id/webhook_token
      # - NOTIFY_TELEGRAM=tg://bot_token/chat_id
      # - NOTIFY_PUSHOVER=pover://user_key@app_token
      # - NOTIFY_SLACK=slack://token_a/token_b/token_c
      # - NOTIFY_EMAIL=mailto://user:pass@gmail.com?to=you@gmail.com
      # - NOTIFY_GOTIFY=gotify://hostname/token
      # - NOTIFY_URLS=                                   # catch-all: comma-separated Apprise URLs
      #
      # AI PROVIDER KEYS (optional)
      # Claude Code can authenticate via web UI (OAuth) or ANTHROPIC_API_KEY.
      # Set these if you want to use additional AI CLIs or API-based auth.
      #
      # - GEMINI_API_KEY=your_key
      # - OPENAI_API_KEY=your_key
      # - CURSOR_API_KEY=your_key

Then:

docker compose up -d

If you want to change the host-side port or bind-mount paths without editing compose, copy .env.example to .env and set:

HOLYCLAUDE_HOST_PORT=3003
HOLYCLAUDE_HOST_CLAUDE_DIR=./data/claude
HOLYCLAUDE_HOST_WORKSPACE_DIR=./workspace

These values are read by Docker Compose on the host. They are not container environment variables.

Every single environment variable is optional. The container runs perfectly with just TZ=UTC. Everything else has sensible defaults or is handled through the web UI.

↑ back to top

The complete reference. Every variable, what it defaults to, what it does.

↑ back to top

This is not a minimal container. This is an entire development workstation.

The full image includes everything above, plus:

Slim users: Missing a package? Ask Claude. It installs npm/pip packages in seconds. System packages (pandoc, ffmpeg) take 1-2 minutes. You get the same capabilities — the full image just has zero wait time.

↑ back to top

Seven AI CLIs. One container. No other Docker image gives you this.

Claude Code is the primary CLI. The others are there because sometimes you want a second opinion, or a specific model's strengths, or you're comparing outputs. Having all of them one Tab away is the whole point.

↑ back to top

HolyClaude works with Ollama as an alternative to an Anthropic subscription. Set two environment variables and use local or cloud models.

See the full setup guide: docs/ollama.md

↑ back to top

graph TB
    subgraph Docker Container
        EP["entrypoint.sh"] --> BS["bootstrap.sh\n(first boot only)"]
        EP --> S6["s6-overlay\n(PID 1)"]
        S6 --> CC["CloudCLI\n(:3001)"]
        S6 --> XV["Xvfb\n(:99)"]
        CC --> CLAUDE["Claude Code CLI"]
        CLAUDE --> TOOLS["Dev Tools\n(Node, Python, Git...)"]
        CLAUDE --> CHROME["Chromium\n(headless)"]
        XV -.-> CHROME
    end

    subgraph Host
        DATA["./data/claude"] -.->|bind mount| HOME["~/.claude"]
        WS["./workspace"] -.->|bind mount| WORK["/workspace"]
    end

    USER["Browser"] -->|":3001"| CC

    style S6 fill:#2d3748,color:#fff
    style CC fill:#6366f1,color:#fff
    style CLAUDE fill:#f59e0b,color:#000

1. Container starts — entrypoint.sh runs as root. Remaps UID/GID to match your host user, pre-creates required files (preventing Docker's "create it as a directory" bug), checks if this is a first boot.

2. First boot only — bootstrap.sh runs once. Copies default settings, memory template, configures git identity. Creates a sentinel file (.holyclaude-bootstrapped) so it never runs again. Your customizations are safe from that point on.

3. s6-overlay takes over as PID 1 — This isn't supervisord. It's s6-overlay, purpose-built for Docker. Supervises CloudCLI and Xvfb. Auto-restarts on crash. Forwards signals. Reaps zombies. Shuts down gracefully.

4. CloudCLI serves the web UI — Port 3001. Browser-based interface to Claude Code with project management, multiple sessions, and plugins (project stats + web terminal included).

5. Xvfb provides a virtual display — Chromium needs a screen to render to, even in "headless" mode. Xvfb gives it a 1920x1080 virtual display at :99. This is why Playwright, screenshots, and Lighthouse all work out of the box.

See docs/architecture.md for the full technical deep-dive — including why we chose s6 over supervisord, why plugins are baked into the image, and why runuser instead of su.

↑ back to top

holyclaude/
├── .github/                 # CI/CD workflows, issue & PR templates
│   ├── FUNDING.yml          # Sponsor/donation links
│   ├── ISSUE_TEMPLATE/      # Bug report, feature request, package request
│   ├── pull_request_template.md
│   ├── SECURITY.md          # Security policy
│   └── workflows/           # Docker build & push automation
├── assets/                  # Logo and banner images
├── config/                  # Claude Code configuration
│   ├── claude-memory-full.md
│   ├── claude-memory-slim.md
│   └── settings.json
├── docs/                    # Extended documentation
│   ├── architecture.md
│   ├── CHANGELOG.md
│   ├── configuration.md
│   ├── dockerhub-description.md
│   ├── ollama.md
│   └── troubleshooting.md
├── scripts/                 # Container lifecycle scripts
│   ├── bootstrap.sh         # First-run setup
│   ├── entrypoint.sh        # Container entrypoint
│   └── notify.py            # Notification helper (Apprise)
├── s6-overlay/              # Process supervision (s6-rc services)
├── Dockerfile               # Single-stage build
├── docker-compose.yaml      # Quick start (minimal config)
├── docker-compose.full.yaml # Full config (all options)
├── LICENSE
└── README.md

↑ back to top

• Your Anthropic authentication and API keys
• Claude Code settings and memory (CLAUDE.md)
• All your code in ./workspace
• Git configuration

• CloudCLI web account — quick signup, that's it

# Delete the sentinel file — NOT the whole folder
rm ./data/claude/.holyclaude-bootstrapped
docker compose restart holyclaude

Never delete ./data/claude/ entirely. That's where your credentials live. Delete the sentinel file if you want a fresh bootstrap. Delete specific config files if you want to reset settings. But never nuke the whole folder.

↑ back to top

Claude Code runs in allowEdits mode by default. This is the safest useful setting:

This is how I personally run it. Edit ./data/claude/settings.json on your host:

{
  "permissions": {
    "defaultMode": "bypassPermissions"
  }
}

Bypass mode means Claude executes any command without confirmation. Fast, powerful, and exactly what you want if you trust what you're building. But allowEdits is the safe default for a reason.

↑ back to top

Walk away from your computer and know when Claude is done. Uses Apprise for notifications — supports 100+ services including Discord, Telegram, Slack, Email, Pushover, Gotify, and more.

To enable:

1. Add one or more NOTIFY_* variables to your compose environment:

   - NOTIFY_DISCORD=discord://webhook_id/webhook_token
   - NOTIFY_TELEGRAM=tg://bot_token/chat_id

2. Inside the container: touch ~/.claude/notify-on

See configuration docs for all supported variables and URL formats.

To disable: rm ~/.claude/notify-on

Events that trigger notifications:

Completely silent when not configured. No NOTIFY_* vars set? No flag file? Zero network calls. Zero log spam. Zero overhead.

↑ back to top

# Pull the latest image
docker compose pull

# Recreate the container with the new image
docker compose up -d

Your data persists in ./data/claude and ./workspace — upgrading only replaces the container, not your files.

To pin a specific version instead of latest:

image: coderluii/holyclaude:1.1.2   # instead of :latest

↑ back to top

- CHOKIDAR_USEPOLLING=1
- WATCHFILES_FORCE_POLLING=true

# On your host machine
id -u  # → this is your PUID
id -g  # → this is your PGID

- PUID=1000
- PGID=1000

See docs/troubleshooting.md for the complete guide including all SMB/CIFS gotchas and the full history of bugs we encountered and fixed.

↑ back to top

These are not HolyClaude bugs — they're upstream issues or intentional trade-offs.

↑ back to top

Want to build the image yourself instead of pulling from Docker Hub? Go for it:

git clone https://github.com/CoderLuii/HolyClaude.git
cd holyclaude

# Build full image
docker build -t holyclaude .

# Build slim image
docker build --build-arg VARIANT=slim -t holyclaude:slim .

# Build for ARM (Apple Silicon, Raspberry Pi, AWS Graviton)
docker buildx build --platform linux/arm64 -t holyclaude .

Then use image: holyclaude instead of image: coderluii/holyclaude:latest in your compose file.

↑ back to top

How does HolyClaude compare to other approaches?

HolyClaude isn't competing with coding agents — it's the infrastructure layer that makes them all work better. It's the container you run them inside.

↑ back to top

What's coming next:

Have an idea? Start a discussion or request a feature.

↑ back to top

Using HolyClaude to build something? We'd love to see it.

Open an issue with the showcase label or submit a PR to add your project here:

Be the first to add your project here.

↑ back to top

Contributions welcome. This project was born from real daily usage, and it gets better when more people use it and find edge cases.

1. Fork it
2. Branch it (git checkout -b feature/something)
3. Commit it
4. Push it
5. PR it

Bugs, feature requests, questions: open an issue.

Use the 📦 Package Request issue template. Include the package name, install method, and which variant (full/slim) it should target.

↑ back to top

HolyClaude is free, open source, and maintained by one developer who uses it every day.

If it saved you time, here's how you can help:

• Star this repo — it's the single biggest thing you can do for visibility
• Share it — tell a friend, post it, tweet it
• Open issues — bug reports and feature requests make HolyClaude better for everyone
• Contribute — PRs are always welcome

↑ back to top

MIT — see LICENSE. Use it however you want.

↑ back to top