HolyClaude

Stop configuring. Start building.

One command. Full AI development workstation. Claude Code, web UI, headless browser, 5 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.

What is this?

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.

:credit_card: Use Your Existing Subscription

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.

Table of Contents

| | Section | |---|---| | :zap: | Quick Start | | :computer: | Platform Support | | :star2: | Why HolyClaude | | :credit_card: | Subscription & Authentication | | :package: | Image Variants | | :whale: | Docker Compose — Quick | | :whale2: | Docker Compose — Full | | :wrench: | Environment Variables | | :rocket: | What's Inside | | :robot: | AI CLI Providers | | :building_construction: | Architecture | | :file_folder: | Project Structure | | :floppy_disk: | Data & Persistence | | :lock: | Permissions | | :bell: | Notifications | | :arrows_counterclockwise: | Upgrading | | :construction: | Troubleshooting | | :warning: | Known Issues | | :hammer_and_wrench: | Building Locally | | :bar_chart: | Alternatives | | :rocket: | Roadmap | | :trophy: | Built with HolyClaude | | :handshake: | Contributing | | :heart: | Support | | :page_facing_up: | License |

:zap: Quick Start

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.

:computer: Platform Support

| Platform | Status | Notes | |----------|--------|-------| | Linux (amd64) | ✅ Fully supported | Native performance, recommended | | Linux (arm64) | ✅ Fully supported | Raspberry Pi 4+, Oracle Cloud, AWS Graviton | | macOS (Docker Desktop) | ✅ Fully supported | Apple Silicon & Intel via Docker Desktop | | Windows (WSL2 + Docker Desktop) | ✅ Fully supported | Requires WSL2 backend | | Synology / QNAP NAS | ✅ Fully supported | Use CHOKIDAR_USEPOLLING=true for SMB mounts | | Kubernetes | 🔜 Coming soon | Helm chart planned |

:star2: Why HolyClaude

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.

| | HolyClaude | Doing it yourself | |---|---|---| | Setup | 30 seconds | 1-2 hours (if it goes well) | | Claude Code | Pre-installed, pre-configured, ready | Install, configure, debug installer hanging, fix WORKDIR | | Web UI | CloudCLI included with plugins | Find a web UI, install it, configure it, wire it to Claude | | Headless browser | Chromium + Xvfb + Playwright, configured | Install Chromium, install Xvfb, configure display :99, fix shm, fix sandbox, fix seccomp... | | AI CLIs | 5 providers, one container | Install each one separately across 3 package managers | | Dev tools | 50+ tools, ready | apt-get install / npm i -g / pip install for the next hour | | Process management | s6-overlay (auto-restart, graceful shutdown) | Write your own supervisord config or hope Docker restart works | | Persistence | Bind mounts, credentials survive everything | Figure out Docker volumes, debug "why is this a directory not a file" | | Updates | docker pull && docker compose up -d | Update 50 tools manually, pray nothing breaks | | Multi-arch | AMD64 + ARM64 | Pray your Dockerfile builds on ARM |

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

:credit_card: Subscription & Authentication

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

What works:

| Authentication method | How | Cost | |----------------------|-----|------| | Claude Max/Pro plan (subscription) | Sign in through CloudCLI web UI — same OAuth flow as desktop | Your existing subscription, no extra charge | | Anthropic API key | Paste your API key in the web UI | Pay-per-use, same Anthropic billing |

What doesn't work:

| | Why | |---|---| | ChatGPT Plus/Pro subscription | That's for chat.openai.com only — doesn't provide API access | | OpenAI API key for Claude | Different company, different API. OpenAI keys work with the Codex CLI (also pre-installed) |

Other AI CLIs included:

| CLI | What you need | |-----|--------------| | Gemini CLI | Google AI API key (GEMINI_API_KEY) | | OpenAI Codex | OpenAI API key (OPENAI_API_KEY) — separate from ChatGPT subscription | | Cursor | Cursor API key (CURSOR_API_KEY) | | TaskMaster AI | Uses your AI provider keys (Anthropic, OpenAI, etc.) |

**HolyClaude is fre