CoderLuii/HolyClaude

🌍 English | Español | Français | Italiano | Português | Deutsch | Русский | हिन्दी | 中文 | 日本語 | 한국어

HolyClaude

Stop configuring. Start building.

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

[!TIP]

Stop maintaining. Start building.

> A hosted AI workstation. Always-on Linux box.

> holycode.cloud

---

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.

v1.6.2 updates Node 26.9.0, Debian Chromium 153.0.8010.47, the bundled AI and deployment CLIs, Python utilities, Playwright bindings and pinned security overlays. CloudCLI's copied SQLite metadata now matches the verified Node 26 artifact, and Vercel's two installed tar layouts are both checked before the checksum-bound replacement is applied. The Docker client remains an opt-in Full-derived recipe; stock images still ship without it.

Release-sensitive facts are also published in contracts/product-facts.json. The release workflow checks that contract against the Dockerfile and Compose files before building images.

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 operates no credential relay. Bundled tools read credentials from container files, bind mounts, or environment variables, then contact the providers you configure directly.

↑ back to top

---

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 | | :mag: | Desloppify | | :llama: | Using Ollama | | :building_construction: | Architecture | | :file_folder: | Project Structure | | :floppy_disk: | Data & Persistence | | :lock: | Permissions | | :shield: | Remote Access & Exposure | | :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 | | :scroll: | Third-Party Software | | :page_facing_up: | License |

↑ back to top

---

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

Want to reach it from outside your network? Don't port-forward it. See Remote Access & Exposure — use Tailscale or Cloudflare Tunnel instead.

↑ back to top

---

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

↑ back to top

---

: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 | 8 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-mounted tool config and workspace survive rebuilds | Figure out Docker volumes, debug "why is this a directory not a file" | | Updates | docker compose 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.

↑ back to top

---

: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 | |---|---| | OpenAI API key for Claude | Different company, different API. OpenAI keys work with the Codex CLI (also pre-installed) |

ChatGPT Plus/Pro subscribers: Your subscription works with the Codex CLI. Run codex login --device-auth inside the container to authenticate with your ChatGPT account. If you need Codex's browser callback flow from your host, expose port 1455 in the full compose template below.

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) or ChatGPT Plus/Pro subscription (codex login --device-auth) | | Cursor | Cursor API key (CURSOR_API_KEY) | | TaskMaster AI | Uses your AI provider keys (Anthropic, OpenAI, etc.) | | Junie | JetBrains account (JetBrains AI subscription) | | OpenCode | Configure via opencode TUI (OpenRouter and other providers) | | Pi Coding Agent | Configure through pi (supports multiple providers) |

HolyClaude is free and open source. You only pay your AI providers for usage, same as you already do. HolyClaude does not relay provider credentials. Bundled tools read them from container files, bind mounts, or environment variables and contact providers directly.

↑ back to top

---

:package: Image Variants

Two flavors. Same quality. Pick your weight class.

| Tag | What you get | Best for | Docker Hub compressed size | |-----|-------------|----------|----------------------------| | latest | Everything pre-installed — every tool, every library, every CLI | Most users. Zero wait time. Claude never has to stop and install something. | Check by architecture | | slim | Core tools only — Claude installs extras on-demand | Smaller VPS, limited disk, metered bandwidth | Check by architecture | | X.Y.Z | Full image, pinned version | Production stability — you control when to update | Same as latest for that release | | X.Y.Z-slim | Slim image, pinned version | Production + small footprint | Same as slim for that release |

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

> Download size varies by release and architecture; check the matching tag on Docker Hub. It reports compressed transfer size. Docker, Synology Container Manager, and NAS filesystems can show a larger unpacked size after layers are extracted. Use slim when disk space or bandwidth matters more than having every tool ready on first boot.

↑ back to top

---

:whale: Docker Compose — Quick

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                           # Retained browser default for this release
    network_mode: bridge
    cap_add:
SYS_ADMIN                          # Current browser profile for this release; hardening is separate
SYS_PTRACE                         # Debugging-related capability
    security_opt:
seccomp=unconfined                 # Current browser profile for this release; hardening is separate
    ports:
"127.0.0.1:3001:3001"              # CloudCLI web UI, localhost only
    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 these browser caps? This release keeps HolyClaude's current browser container profile in place. Chromium does not universally require SYS_ADMIN, SYS_PTRACE, or seccomp=unconfined, and SYS_PTRACE is debugging-related. Keep the web UI bound to 127.0.0.1 unless you put a real private tunnel or access layer in front of it. Treat any hardening pass as a separate change.

Why shm_size: 2g? Docker gives containers 64MB of shared memory by default. HolyClaude keeps 2GB as the retained browser default for this release because Chromium uses /dev/shm heavily for tab rendering. At 64MB, tabs crash randomly. For heavy browser use (many tabs, complex pages), increase to 4GB.

↑ back to top

---

:whale2: Docker Compose — Full

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/master/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                          # Current browser profile for this release; hardening is separate
SYS_PTRACE                         # Debugging-related capability (strace, lsof)
    security_opt:
seccomp=unconfined                 # Current browser profile for this release; hardening is separate
    ports:
      #
      # CloudCLI web UI — this is the only port you need.
      # Override the host-side port from .env if 3001 is already in use.
      #
"127.0.0.1:${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.
      #
      # - "127.0.0.1:3000:3000"            # Next.js / Express
      # - "127.0.0.1:4321:4321"            # Astro
      # - "127.0.0.1:5173:5173"            # Vite
      # - "127.0.0.1:8787:8787"            # Wrangler (Cloudflare Workers)
      # - "127.0.0.1:9229:9229"            # Node.js debugger
      # - "127.0.0.1:1455:1455"            # Codex auth callback port
      # - "127.0.0.1:2222:22"              # Optional SSH, localhost/VPN only
      # - "127.0.0.1:60000-60010:60000-60010/udp"  # Optional Mosh UDP range
    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
      #
      # OPTIONAL SSH/MOSH REMOTE SHELL
      # Keep authorized_keys outside .claude and /workspace. Mount it read-only.
      #
      # - ./data/ssh/authorized_keys:/run/holyclaude-ssh/authorized_keys:ro
      # - holyclaude-ssh:/var/lib/holyclaude-ssh
    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
      # Docker-style UID/GID remapping. Run id -u and id -g on your host.
      # Rootless Podman users should use docker-compose.podman-rootless.yaml instead.
      #
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=tgram://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
      #
      # WEB UI BASE PATH (optional)
      # Use only when a reverse proxy mounts HolyClaude below a path.
      # Example: Tailscale Serve --set-path=/holyclaude
      # Do not add a trailing slash.
      #
      # - HOLYCLAUDE_BASE_PATH=/holyclaude
      #
      # CODEX PERMISSION MODES (optional)
      # CloudCLI Codex chat uses this only when a request omits permissionMode.
      # The current browser client sends permissionMode explicitly.
      # Raw codex CLI reads HOLYCLAUDE_CODEX_CLI_PERMISSION_MODE only when first creating ~/.codex/config.toml.
      # Valid values: default, acceptEdits, bypassPermissions. Recommended: acceptEdits.
      # bypassPermissions gives full access with no approval. Use it only for trusted local workspaces.
      #
      # - HOLYCLAUDE_CODEX_CHAT_PERMISSION_MODE=acceptEdits
      # - HOLYCLAUDE_CODEX_CLI_PERMISSION_MODE=acceptEdits
      #
      # SSH/MOSH REMOTE SHELL (optional, disabled by default)
      # Keep this behind localhost, VPN, Tailscale, or a firewall.
      #
      # - HOLYCLAUDE_SSH_ENABLE=false
      # - HOLYCLAUDE_SSH_AUTHORIZED_KEYS=/run/holyclaude-ssh/authorized_keys
      # - HOLYCLAUDE_SSH_HOST_KEYS_DIR=/var/lib/holyclaude-ssh/host_keys
      # - HOLYCLAUDE_MOSH_ENABLE=false
      # - HOLYCLAUDE_MOSH_UDP_START=60000
      # - HOLYCLAUDE_MOSH_UDP_END=60010

volumes:
holyclaude-ssh:

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.

What each section controls:

| Section | What it does | When to change it | |---------|-------------|-------------------| | Timezone | Container clock | Always — set to your local TZ | | Performance | Node.js memory ceiling | Only if you hit OOM errors on large projects | | User mapping | File permissions between container and host | Docker users: match id -u and id -g. Rootless Podman users: u