DOCSEARCHbyAlgolia
Submit Docs

HolyClaude Documentation

repository·master·Indexed 25 days ago

https://github.com/coderluii/holyclaude

A containerized, self-hosted AI development workstation providing a full environment with Claude Code, a web UI, headless browsers, and over 50 developer tools. It bundles multiple AI CLIs including Gemini, OpenAI Codex, Cursor, TaskMaster AI, Junie, OpenCode, and Pi Coding Agent, designed to eliminate manual configuration for AI CLIs and browser-based testing tools in Docker.

Tokens
43.6K
Snippets
109
Records
218
Agent score
71%

What's inside HolyClaude

  1. Overview of HolyClaude packages and tools

    master

    HolyClaude provides a complete development workstation in a container. It is available in two variants: slim and full.

    Core Packages (Both Variants)

    • Node.js 26 + npm: Includes typescript, tsx, pnpm, vite, esbuild, eslint, prettier, serve, nodemon, concurrently, and dotenv-cli.
    • Python 3: Includes requests, httpx, beautifulsoup4, lxml, Pillow, pandas, numpy, openpyxl, python-docx, jinja2, markdown, pyyaml, python-dotenv, rich, click, tqdm, desloppify, bandit, tree-sitter, and playwright (1.61.0).
    • System Tools: git, gh (GitHub CLI), ripgrep (rg), fd, fzf, bat, tree, jq, curl, wget, tmux, htop, lsof, strace, imagemagick, chromium, psql, redis-cli, sqlite3, openssh-client, openssh-server, and mosh.
    • Core AI CLIs:
      • claude (Claude Code)
      • gemini (Gemini CLI)
      • codex (OpenAI Codex)
      • cursor (Cursor)
      • task-master (TaskMaster AI)

    Additional Packages (Full Image Only)

    • Additional AI CLIs:
      • junie (JetBrains)
      • opencode (Open-source/OpenRouter)
      • pi (Pi Coding Agent)
    • Deployment & ORMs: wrangler, @cloudflare/next-on-pages, vercel, netlify-cli, az (Azure), prisma, drizzle-kit, pm2, eas-cli.
    • Python & Media: reportlab, weasyprint, cairosvg, fpdf2, PyMuPDF, pdfkit, img2pdf, xlsxwriter, xlrd, matplotlib, seaborn, python-pptx, fastapi, uvicorn, pandoc, ffmpeg, and libvips-dev.
    • Other: lighthouse, @lhci/cli, sharp-cli, json-server, http-server, and @marp-team/marp-cli.

  2. What is HolyClaude?

    master

    HolyClaude is a containerized AI development workstation designed to provide a ready-to-use environment for AI-driven development. It eliminates the complex manual setup of tools like Claude Code, headless browsers (Playwright/Chromium), and various AI CLIs by providing a pre-configured Docker environment.

    Key features include:

    • Claude Code Integration: Runs the actual Claude Code CLI (not a wrapper).
    • Web UI: Access your development environment via a browser.
    • Headless Browser Support: Includes Playwright and Chromium configured to work within Docker (solving common issues like shared memory limits and Xvfb configuration).
    • Tooling Suite: Includes 8 AI CLIs, 50+ developer tools (TypeScript, Python, GitHub CLI, etc.), and database clients.
    • Subscription Compatibility: Works with existing Anthropic Max/Pro plans via OAuth or direct Anthropic API keys.

  3. Overview of the HolyClaude Slim Environment

    master

    The HolyClaude Slim variant is a lightweight Docker container running Debian Bookworm. It is designed for developers to run AI-driven coding sessions with pre-installed core tools.

    Key Environment Details:

    • User: claude (UID/GID configurable via PUID/PGID).
    • Working Directory: /workspace (bind-mounted from host for persistence).
    • Home Directory: /home/claude.
    • Persistent Storage: ~/.claude/ is bind-mounted; settings and file-based credentials survive rebuilds.
    • Process Management: Managed by s6-overlay v3.
    • Virtual Display: Xvfb at :99 for headless browser operations.

    Running Services:

    • CloudCLI: Web UI for Claude Code on port 3001.
    • Xvfb: Virtual display for headless Chromium on port :99.
    • sshd: Optional SSH login on port 22 (enabled via HOLYCLAUDE_SSH_ENABLE=true).

  4. Overview of the HolyClaude Full Variant Environment

    master

    The HolyClaude Full Variant is a pre-configured Docker container environment designed for AI-assisted development. It runs on Debian Bookworm (slim) and uses s6-overlay v3 as a process manager.

    Key Environment Details:

    • User: claude (UID/GID configurable via PUID/PGID).
    • Working Directory: /workspace (bind-mounted from host).
    • Home Directory: /home/claude.
    • Persistent Storage: ~/.claude/ is bind-mounted, ensuring settings, credentials, and the claude-memory-full.md file survive container rebuilds.
    • Virtual Display: Xvfb runs at :99 for headless browser operations.

    Running Services:

    • CloudCLI: Web UI for Claude Code on port 3001.
    • Xvfb: Virtual display for headless Chromium on port :99.
    • sshd: Optional SSH login on port 22 (enabled via HOLYCLAUDE_SSH_ENABLE=true).

  6. Configure Desloppify

    master

    Desloppify is a code quality tool included in the full image. It is passive by default and does not modify your workspace unless explicitly run.

    Manual Usage:

    1. Run a scan: desloppify scan --path .
    2. Apply changes: desloppify next
    3. Important: Add .desloppify/ to your project's .gitignore after scanning.

    Automatic Setup: Control global skill setup via the HOLYCLAUDE_DESLOPPIFY_SETUP environment variable. Valid values:

    • off (default)
    • all (expands to claude,codex,gemini)
    • Specific providers: claude, codex, gemini, or opencode (or comma-separated subsets).

  7. Understand HolyClaude Data Persistence

    master

    HolyClaude is designed to survive docker compose down && docker compose up cycles. Most critical data is stored in bind-mounted directories on your host.

    Data TypeContainer PathHost PathSurvives Rebuild?
    Claude settings & tool config/home/claude/.claude./data/claudeYes
    Claude Code session (OAuth, etc)/home/claude/.claude.json./data/claude/.claude.json.persistYes
    Code and projects/workspace./workspaceYes
    CloudCLI account/home/claude/.cloudcli(Container-local)No

    Note on CloudCLI Accounts: By default, the CloudCLI account database is container-local and wiped on rebuild. To persist it, use a named Docker volume.

  8. Use your existing Anthropic subscription

    master

    HolyClaude runs the official Claude Code CLI from Anthropic. It is not a wrapper or a proxy. You can use your existing Anthropic credentials directly:

    • Claude Max/Pro Plans: Authenticate via the web interface (OAuth), identical to the Claude Code desktop experience.
    • Anthropic API Keys: Configure your key via the web interface using your existing billing.

    Security Note: HolyClaude does not operate a credential relay. Tools read credentials from container files, bind mounts, or environment variables and contact providers directly.

  9. Understand HolyClaude data persistence and volume mapping

    master

    HolyClaude uses specific container paths to manage data. To ensure your settings, sessions, and code survive container rebuilds or docker compose down commands, you must map the following host directories to the corresponding container paths:

    Data TypeContainer PathHost Path (Example)Survives Rebuild?
    Claude settings & tool config/home/claude/.claude./data/claudeYes
    Claude Code session (OAuth/onboarding)/home/claude/.claude.json./data/claude/.claude.json.persistYes
    Your code and projects/workspace./workspaceYes
    CloudCLI account/home/claude/.cloudcli(Container only by default)No (opt-in available)

    Important Warnings:

    • Never delete the entire ./data/claude/ directory on your host, as it contains your saved Claude Code sessions and tool configurations.
    • Do NOT bind-mount CloudCLI data to a network share (NAS, SMB/CIFS, NFS). CloudCLI uses SQLite, which will fail with database is locked errors on network mounts. Use a local SSD path or a named Docker volume instead.

  10. Manage HolyClaude data and persistence

    master

    HolyClaude uses specific host directories to ensure your Claude Code sessions, configurations, and projects survive container rebuilds or recreates.

    Data TypeContainer PathHost PathSurvives Rebuild?
    Claude Config & Tools/home/claude/.claude./data/claudeYes
    Claude Code Session (OAuth/Onboarding)/home/claude/.claude.json./data/claude/.claude.json.persistYes
    Code & Projects/workspace./workspaceYes
    CloudCLI Account/home/claude/.cloudcli(Default: Container only)No (unless opt-in)

    Important: Do NOT use network mounts (NAS, SMB, NFS) for ./data/claude as CloudCLI uses SQLite, which will cause database is locked errors. Use local SSD bind mounts or Docker named volumes.

  11. How HolyClaude handles configuration and persistence

    master

    HolyClaude uses several design patterns to manage user data and settings:

    Sentinel-based Bootstrap

    To prevent user customizations from being overwritten during container restarts, HolyClaude uses a sentinel pattern:

    • First boot: The bootstrap process installs fresh default settings and memory.
    • Subsequent boots: The bootstrap detects the existing configuration and preserves user customizations.
    • Manual Reset: To force a reset to defaults, delete the sentinel file.

    Data Persistence via Bind Mounts

    By default, HolyClaude encourages the use of bind mounts rather than named volumes. This allows users to manage their code and configuration files directly on their host filesystem for easier backup and inspection.

    Exception: The CloudCLI account database (SQLite) is an exception. Because SQLite requires local filesystem locking, it is offered as an opt-in named volume. The image pre-creates /home/claude/.cloudcli to support Docker copy-up and custom PUID/PGID values.

  12. How Claude session persistence works

    master

    HolyClaude includes a dedicated service to prevent loss of Claude session data. The Claude Session Persistence Service runs as an s6 longrun service. It periodically saves the live state of ~/.claude.json to a backup file at ~/.claude/.claude.json.persist.

    Key behaviors:

    • Sync Interval: The default sync interval is 60 seconds, but this can be configured via the HOLYCLAUDE_CLAUDE_JSON_SYNC_INTERVAL environment variable.
    • Safety Checks: The service will refuse to replace a valid saved session with files that are empty, invalid, symlinked, oversized, or contain only onboarding data.
    • Startup Restore: During container startup, the entrypoint.sh script attempts to restore the session from .claude.json.persist back to ~/.claude.json before other services start.
    #!/command/with-contenv sh
while true; do
  node /usr/local/bin/persist-claude-json.mjs --save-live --quiet
  sleep "${HOLYCLAUDE_CLAUDE_JSON_SYNC_INTERVAL:-60}"
done