Run HolyClaude as a Local Claude Code Workstation

The useful HolyClaude article is not a celebration of one-command setup. A one-command AI workstation is valuable only if the operator understands what the command starts.

HolyClaude packages Claude Code, CloudCLI, Codex, other AI CLIs, Xvfb, Chromium, Playwright, development tools, bind mounts, and process supervision into one Docker container. That can save hours for a developer who wants a browser-accessible Claude Code workstation. It can also create a large local shell surface if the web UI is exposed carelessly. The magazine version should teach the operating boundary, not repeat the launch pitch.

The adoption boundary

Use HolyClaude when setup friction is the bottleneck: remote home server, disposable AI workstation, browser-based Claude Code, Playwright screenshots, Codex in the same container, or a consistent toolchain across machines. Skip it when native Claude Code is already enough. Also skip it if you cannot reason about Docker capabilities, bind mounts, persisted credentials, and port exposure. This is not a safer default because it is containerized. It is a convenience layer with a very real operations surface.

What the sources prove

The README proves the scope: HolyClaude runs the real Claude Code CLI, supports existing Anthropic subscriptions or API keys, includes CloudCLI, and starts at http://localhost:3001. The compose files prove the boundary: the web UI binds to 127.0.0.1:3001, credentials persist under ./data/claude, and projects live under ./workspace. The architecture docs prove the internals: entrypoint UID/GID remapping, first-boot bootstrap, s6-overlay as PID 1, CloudCLI as a long-running service, and Xvfb at display :99. The configuration guide proves the risk: Chromium needs extra Docker privileges, and bypass permissions can give Codex full access inside mounted volumes.

Start with the quick compose file

The minimal path is mkdir holyclaude && cd holyclaude, create the provided docker-compose.yaml, run docker compose up -d, and open http://localhost:3001. Keep the first run boring. Do not expose extra dev server ports. Do not change the permission mode. Do not mount your whole home directory as /workspace. The quick compose file already gives the important defaults: coderluii/holyclaude:latest, shm_size: 2g, localhost-only port binding, ./data/claude for Claude state, and ./workspace for projects.

Understand the two bind mounts

The data mount is where credentials and agent settings live: ./data/claude:/home/claude/.claude. The workspace mount is where code lives: ./workspace:/workspace. Treat those as the trust boundary. If CloudCLI, Claude Code, Codex, or a shell command can touch it, it is in scope. Back up ./data/claude carefully, because it contains settings and authentication state. Do not delete that directory casually. The docs say deleting only .holyclaude-bootstrapped reruns bootstrap; deleting the whole data directory wipes credentials.

Docker isolation is reduced for a reason

The compose files add SYS_ADMIN, SYS_PTRACE, and seccomp=unconfined. HolyClaude documents why: Chromium and debugging tools need capabilities that the default Docker sandbox does not provide. That is a legitimate engineering tradeoff for a browser-capable workstation. It is also the reason this should not be treated like a low-risk web app. The container boundary still helps, but the browser stack and debug permissions mean the safe deployment pattern is localhost or private tunnel, not a public route.

Remote access is the make-or-break section

The README says not to port-forward 3001 to the public internet. That warning is not cosmetic. CloudCLI exposes a full shell through its web terminal plugin. It can run arbitrary code and read or write the mounted /workspace. If remote access is needed, use Tailscale or Cloudflare Tunnel with an access layer. If someone insists on a reverse proxy, add TLS, IP allowlisting, SSO, keep acceptEdits, and rotate credentials if anything looks wrong. In most personal setups, Tailscale is the cleaner answer.

Keep permission modes conservative

The shipped Claude settings use acceptEdits. The configuration guide recommends acceptEdits for Codex chat and raw Codex CLI settings too. bypassPermissions is not just a convenience flag. It gives Codex full access with no approval to anything reachable through /workspace, /home/claude, and other mounts. That may be acceptable for a disposable local sandbox with a narrow test repo. It is not acceptable for a broad workspace, a shared server, or any instance reachable from outside a private network.

Use it for browser-heavy agent work

HolyClaude makes the most sense when a coding agent must drive a browser. The architecture includes Xvfb and a configured Chromium path so Playwright, screenshots, and Lighthouse have a display. That solves real Docker pain: default shared memory, Chromium sandboxing, display setup, and process supervision. For backend-only tasks, this is probably more image than needed. For frontend QA, browser screenshots, Cloudflare/Vercel deployment CLIs, and AI CLI switching, the bundled workstation can be worth the weight.

Run a first acceptance checklist

After startup, verify five things before trusting it. First, docker compose ps shows the service healthy. Second, http://localhost:3001 opens only from the host or private tunnel. Third, a test file created inside /workspace appears under ./workspace on the host with the right ownership. Fourth, Claude authentication persists after docker compose restart. Fifth, Codex is left on acceptEdits or default unless the mounted workspace is disposable. If any of these fail, fix the container boundary before doing real project work.

Where not to use it

Do not use HolyClaude as a public cloud IDE without a real access-control layer. Do not point it at a monorepo containing secrets unless the operator understands the web terminal and permission mode. Do not enable bypassPermissions for convenience on a shared server. Do not mount more directories than the agent actually needs. Do not assume that local credential storage means low risk. This is a powerful shell and browser workspace wrapped in Docker.

A deployment shape I would accept

For personal use, I would run the quick compose file on a trusted host, keep 127.0.0.1:3001:3001, access it over SSH port forwarding or Tailscale, mount one project directory, leave permission modes conservative, and pin image versions for any long-running setup. For a small team, I would require Cloudflare Access or equivalent SSO, separate workspaces per user, no public port forwarding, and a written rotation plan for Anthropic and OpenAI credentials. Anything looser turns convenience into exposure.

Save HolyClaude as a local AI workstation article. It is valuable when Docker packaging removes real Claude Code, Codex, browser, and Playwright setup friction, but only if localhost binding, private access, mounted data, and permission modes are treated as first-class engineering decisions.

Practical takeaway

Start with the quick compose file, leave the web UI bound to 127.0.0.1:3001, mount only ./workspace, keep credentials under ./data/claude, and use acceptEdits. Do not port-forward CloudCLI. Use Tailscale, SSH forwarding, or Cloudflare Access for remote use. Before real work, verify ownership, authentication persistence, and Codex permission mode.