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

In v1.5.5, Git global configuration and GitHub CLI authentication survive container replacement through the existing ./data/claude mount. Node moves to 26.5.1, GitHub CLI to 2.97.0, npm to 11.19.0, Vite to 8.2.0, Wrangler to 4.116.0, OpenCode to 1.18.10, and Python Markdown to 3.10.3. CloudCLI stays at the verified 1.36.3 baseline with a refreshed production dependency tree. Playwright remains aligned at 1.61.0 for Node and Python, with no runtime browser download.

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

↑ 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

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

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:

What doesn't work:

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:

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.

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

Docker Hub reports compressed transfer size. Docker, Synology Container Manager, and NAS filesystems can show a larger unpacked size after layers are extracted. That is expected; 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:

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

:wrench: Environment Variables

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

↑ back to top

:rocket: What's Inside

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

Both variants (full + slim)

Full image only (additional packages)

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

:robot: AI CLI Providers

The full image ships eight AI CLIs. The slim image ships the five core CLIs.

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.

OpenCode is the full-image path for OpenRouter and multi-provider model routing. Configure it inside opencode; free model availability depends on OpenRouter and provider account limits, not HolyClaude.

↑ back to top

:mag: Desloppify

Desloppify ships in both images as the desloppify command. It is passive by default. HolyClaude does not run scans, create .desloppify/, edit .gitignore, or change your mounted workspace unless you run Desloppify yourself.

Use it inside a project:

desloppify scan --path .
desloppify next

After you use scans in a project, add .desloppify/ to that project's .gitignore.

Optional global skill setup is controlled by HOLYCLAUDE_DESLOPPIFY_SETUP.

OpenCode can also discover Claude-compatible skills from ~/.claude/skills, so all does not include opencode. Do not combine claude and opencode in automatic setup; HolyClaude warns and skips opencode to avoid duplicate skill discovery. If OPENCODE_CONFIG_DIR is set, HolyClaude also skips automatic OpenCode setup because Desloppify writes to the standard ~/.config/opencode path.

Desloppify also supports these manual upstream targets if you want to configure them yourself: cursor, copilot, windsurf, qwen, amp, rovodev, droid, and hermes.

↑ back to top

:llama: Using Ollama

HolyClaude works with Ollama as an alternative to an Anthropic subscription. The supported setup path is ANTHROPIC_AUTH_TOKEN=ollama plus ANTHROPIC_BASE_URL=<your Ollama endpoint>.

See the full setup guide: docs/ollama.md

↑ back to top

:building_construction: Architecture

graph TB
    subgraph Docker Container
        EP["entrypoint.sh"] --> CP["Persist Git and gh config\n(every boot)"]
        CP --> BS["bootstrap.sh\n(first boot only)"]
        EP --> S6["s6-overlay\n(PID 1)"]
        S6 --> CC["CloudCLI\n(:3001)"]
        S6 --> XV["Xvfb\n(:99)"]
        S6 -. optional .-> SSH["sshd\n(:22)"]
        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

How the pieces fit together

1. Container starts — entrypoint.sh runs as root for Docker and remaps UID/GID there. In rootless Podman keep-id mode, it skips root-only repairs because the container is already running as the target user. In both paths it restores the saved Claude Code session and prepares persistent Git and GitHub CLI configuration before checking if this is a first boot.

2. Every boot — HolyClaude links global Git config, XDG Git config, and GitHub CLI config into the existing .claude mount. Missing identity values are seeded without replacing manual changes.

3. First boot only — bootstrap.sh copies default settings and the memory template, then creates .holyclaude-bootstrapped. Your customizations are safe from that point on.

4. s6-overlay takes over as PID 1 — This isn't supervisord. It's s6-overlay, purpose-built for Docker. Supervises CloudCLI, Xvfb, Claude session sync, and optional sshd when you explicitly enable it. Auto-restarts on crash. Forwards signals. Reaps zombies. Shuts down gracefully.

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

6. Xvfb provides a compatibility display — Xvfb stays available at :99 for tools that use a headed display. Modern headless Chromium, Playwright, and Lighthouse do not universally require Xvfb.

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

:file_folder: Project Structure

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               # Multi-stage build
├── docker-compose.yaml      # Quick start (minimal config)
├── docker-compose.full.yaml # Full config (all options)
├── docker-compose.podman-rootless.yaml # Rootless Podman keep-id profile
├── LICENSE
└── README.md

↑ back to top

:floppy_disk: Data & Persistence

HolyClaude restores the saved Claude Code session before startup can create a fresh default file. That keeps container rebuilds and recreates from replacing a real OAuth/API session with onboarding state.

What survives docker compose down && docker compose up:

• File-based Anthropic authentication and Claude Code API-key settings
• Claude Code settings, memory (CLAUDE.md), and OAuth session (no re-login)
• All your code in ./workspace
• Git global configuration, aliases, and XDG Git settings
• GitHub CLI configuration and authentication
• Codex, Gemini, and Cursor file-based config and authentication stored below /home/claude/.claude (since v1.1.7). Environment-provided keys remain in your Compose or host environment.

What you'll redo (10 seconds):

• CloudCLI web account — quick signup, that's it (unless you opt into persistence below)

Re-triggering first-boot setup:

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

Protect ./data/claude/. It contains saved Claude Code sessions and may now contain GitHub credentials in .config/gh/hosts.yml. Do not commit it, share it broadly, or place it in an unencrypted backup. Delete only the specific state you intend to reset.

Persisting the CloudCLI account (optional, local storage only)

By default, the CloudCLI account database (~/.cloudcli) is container-local and gets wiped on rebuild. Re-creating the account takes 10 seconds, so most people leave it as-is.

CloudCLI is a single-user service. Remote access shares the same CloudCLI account, /workspace, and mounted credential context; it does not create separate users or tenant isolation.

If you want it to survive rebuilds, add a named Docker volume to your compose file:

services:
  holyclaude:
    volumes:
      - ./data/claude:/home/claude/.claude
      - ./workspace:/workspace
      - cloudcli-data:/home/claude/.cloudcli   # add this line

volumes:
  cloudcli-data:                                # and this block

HolyClaude prepares this directory before CloudCLI starts. Fresh Docker volumes inherit the image's claude:claude ownership. Existing volumes are repaired to the configured PUID/PGID during normal root-starting Docker startup. If the mount is read-only or cannot be repaired, startup stops with the exact path and UID/GID instead of letting CloudCLI repeat unable to open database file.

For rootless Podman, use docker-compose.podman-rootless.yaml. Its keep-id mapping and :Z labels let the existing host user write the mounted state without a privileged ownership repair. :Z handles SELinux labeling; :U rewrites host ownership and is not the default.

Do NOT bind-mount ./data/cloudcli on a network share (NAS, SMB/CIFS, NFS). CloudCLI stores its account in SQLite, and SQLite's file locking breaks on network mounts. You'll hit database is locked errors constantly. Named volumes live on the Docker engine's local filesystem, which is why this works — bind mounts pointing at a NAS will not.

A bind mount to a local SSD path is fine too, just keep it off any network share.

↑ back to top

:lock: Permissions

Claude Code runs in acceptEdits mode by default. This is the shipped setting:

Want full bypass? (power users)

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

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

Bypass mode means Claude executes commands without confirmation. It is powerful, but it can also run destructive commands quickly. Keep the shipped acceptEdits default unless you trust the workspace and every prompt you run.

Codex Permission Modes

HolyClaude also ships configurable near-parity permission modes for Codex, with separate controls for CloudCLI Codex chat and the raw codex CLI.

Valid values for both are default, acceptEdits, and bypassPermissions. acceptEdits is the fallback recommended for trusted self-hosted workspaces. The current CloudCLI browser client sends an explicit permissionMode, and that request value wins. HOLYCLAUDE_CODEX_CHAT_PERMISSION_MODE is only the fallback for direct WebSocket/API clients or custom frontends that omit it. For the raw codex CLI, default is the first-boot default; the setting only seeds a new ~/.codex/config.toml, existing configs are not overwritten, and the generated value persists until you edit that file yourself.

bypassPermissions maps Codex to full access with no approval. Inside Docker, that still runs within the container and mounted volumes, but it can read and change anything reachable through those mounts, especially /workspace and persisted config under /home/claude. Use it only for trusted local workspaces, and don't expose CloudCLI directly to the public internet.

↑ back to top

:shield: Remote Access & Exposure

HolyClaude binds CloudCLI to 127.0.0.1:3001 by default. That keeps the web UI on the Docker host only, which is right for a laptop or a home server you reach over SSH.

The moment you want to reach it from outside your network, read this section.

Don't port-forward it to the public internet

I'll say it flat out: do not punch a hole in your router and expose 3001 to the open internet. Not even with a password. Here's why:

• CloudCLI exposes a full shell through the web terminal plugin
• It can run arbitrary code, install packages, and read/write your mounted /workspace
• It holds your Anthropic OAuth tokens and API keys
• Basic auth / app-level passwords get brute-forced, credential-stuffed, and scraped out of logs
• One leaked password = someone else has a paid Claude Code instance running on your box with your money

A password is a speed bump, not a door. Treat HolyClaude like you'd treat an SSH session: never on the open internet without a proper tunnel in front of it.

Use a proper tunnel instead

These are the two options I actually recommend:

Both avoid forwarding HolyClaude's application port through your router. Tailscale provides encrypted mesh transport and identity controls. Cloudflare Tunnel provides encrypted transport to Cloudflare's edge; configure Cloudflare Access separately when you need identity-based access controls and Access audit logs.

Tailscale subpath mounts

If you mount HolyClaude below a path, set the same path inside the container:

environment:
  - HOLYCLAUDE_BASE_PATH=/holyclaude

Then publish that path with Tailscale Serve:

sudo tailscale serve --bg --https=443 --set-path=/holyclaude http://127.0.0.1:3001

Use no trailing slash in HOLYCLAUDE_BASE_PATH. If you serve HolyClaude at the hostname root, leave this unset.

Optional SSH and Mosh

HolyClaude also ships sshd and Mosh for people who want a direct terminal from a phone, laptop, NAS, or VPN connection. It is off by default. Nothing listens on port 22 unless you enable it.

This is a remote shell into the same container that holds your /workspace and Claude state. Treat it like SSH to your dev box:

• key-only login as claude
• no password auth
• no root login
• no authorized_keys under .claude or /workspace
• no public internet port forwarding

Safe setup shape:

services:
  holyclaude:
    ports:
      - "127.0.0.1:2222:22"
      - "127.0.0.1:60000-60010:60000-60010/udp"
    volumes:
      - ./data/ssh/authorized_keys:/run/holyclaude-ssh/authorized_keys:ro
      - holyclaude-ssh:/var/lib/holyclaude-ssh
    environment:
      - HOLYCLAUDE_SSH_ENABLE=true
      - HOLYCLAUDE_MOSH_ENABLE=true

volumes:
  holyclaude-ssh:

Prepare the public key file on the host:

mkdir -p data/ssh
cp ~/.ssh/id_ed25519.pub data/ssh/authorized_keys

Connect over SSH:

ssh -p 2222 claude@127.0.0.1

Connect over Mosh when UDP is reachable:

mosh --ssh="ssh -p 2222" -p 60000:60010 claude@127.0.0.1

Bind those ports to localhost, a VPN interface, or a firewall-restricted address. If you change 127.0.0.1 to 0.0.0.0, you are taking responsibility for that exposure.

If you insist on exposing it directly (please don't)

If you absolutely have to skip the tunnel (self-hosting tutorial, isolated lab network, whatever), at the very minimum:

1. Put a reverse proxy in front of it (Caddy, nginx, Traefik) with real TLS
2. Add IP allowlisting at the firewall or proxy level — only your known IPs
3. Keep the shipped acceptEdits default unless you have a clear reason to use bypassPermissions
4. Rotate your Anthropic credentials if anything looks off
5. Run behind Cloudflare Access or similar SSO, not basic auth

Even with all that, the risk surface is huge. Use Tailscale or Cloudflare Tunnel. They're free, they take five minutes to set up, and they're what I personally use.

↑ back to top

:bell: Notifications

Walk away from your computer and know when a task is done. Claude Code hooks, raw CLI hooks for Codex and Gemini CLI, and CloudCLI Codex chat completion/failure events use the same Apprise setup. Apprise 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=tgram://bot_token/chat_id
   

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

Telegram uses Apprise's tgram:// scheme. Legacy Telegram values are still accepted, but new setups should use tgram://.

Test the setup without sending a message:

docker compose exec holyclaude /usr/local/bin/notify.py test --dry-run --debug

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

:arrows_counterclockwise: Upgrading

Upgrading from a version before v1.5.5? If the current container holds git config --global or gh auth state that is not already in ./data/claude, migrate it before recreating the container. Follow Git and GitHub CLI recovery. Removing the old container first can discard that state.

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

Do not update CloudCLI inside the container with cloudcli update or npm install -g @cloudcli-ai/cloudcli@latest. HolyClaude ships a patched CloudCLI runtime, so the supported update path is the Docker image:

docker compose pull && docker compose up -d

To pin a specific version instead of latest:

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

↑ back to top

:construction: Troubleshooting

docker compose pull && docker compose up -d

docker compose pull && docker compose up -d

localStorage.setItem('web-terminal-disable-webgl', 'true')

- 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

mkdir -p data/claude data/cloudcli workspace
podman compose -f docker-compose.podman-rootless.yaml up -d

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

:warning: Known Issues

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

↑ back to top

:hammer_and_wrench: Building Locally

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 .

This source release vendors the patched CloudCLI package under vendor/artifacts/, so docker build installs that bundled @cloudcli-ai/cloudcli tarball instead of downloading a moved package from npm.

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

↑ back to top

:bar_chart: Alternatives

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

:rocket: Roadmap

What's coming next:

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

↑ back to top

:trophy: Built with HolyClaude

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

:handshake: Contributing

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.

Get in touch

Want a tool added?

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

↑ back to top

:heart: Support

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

:scroll: Third-Party Software

The HolyClaude Docker image includes third-party software, each under its own license. Notable components:

See THIRD-PARTY-NOTICES for full details including modification notices. HolyClaude's own source code is MIT licensed.

↑ back to top

:page_facing_up: License

MIT — see LICENSE. Use it however you want.

↑ back to top