Forem: CoderLuii

HolyCode: OpenCode in Docker with 30+ Tools, Persistent State, and No API Key Required

CoderLuii — Tue, 31 Mar 2026 08:25:01 +0000

You get your dev environment exactly right. Then you switch machines. Or rebuild a container. Or your system decides today is the day it dies.

Suddenly you're reinstalling tools. Hunting down config files. Re-entering API keys. Wondering why ripgrep isn't on PATH anymore. Figuring out why Chromium won't launch. Then Xvfb isn't configured. Then the UID inside the container doesn't match your host and everything is permission denied.

I built HolyCode after solving every single one of those problems.

What HolyCode Is

HolyCode wraps OpenCode, an AI coding agent with a built-in web UI, in a Docker container with everything already wired up. 30+ dev tools, two language runtimes, a headless browser stack, process supervision via s6-overlay, and support for 10+ AI providers. Pull the image, run one compose command, open your browser. That's the whole setup.

Quick Start

Step 1. Create a docker-compose.yaml:

services:
  holycode:
    image: coderluii/holycode:latest
    container_name: holycode
    restart: unless-stopped
    shm_size: 2g
    ports:
      - "4096:4096"
    volumes:
      - ./data/opencode:/home/opencode
      - ./workspace:/workspace
    environment:
      - PUID=1000
      - PGID=1000
      - ANTHROPIC_API_KEY=your-key-here

Step 2. Start it:

docker compose up -d

Step 3. Open http://localhost:4096.

You're in. OpenCode's web UI is running with all tools available.

One thing worth calling out: shm_size: 2g is required. Chromium crashes with Docker's default 64MB. This is a known Docker + Chromium issue and the image handles everything else, but you need to set this in your compose file.

What's Inside

The image ships with:

Dev tools: git, ripgrep, fd, fzf, bat, eza, lazygit, delta, gh (GitHub CLI), htop, tmux, vim, jq, curl, wget, tree, and more. Everything you would install one by one anyway.

Language runtimes: Node.js 22 (LTS) with npm, Python 3 with pip and venv support. Native npm addon compilation (build-essential, pkg-config) is included.

Browser stack: Chromium, Xvfb, and Playwright. Pre-configured and supervised. Headless browser automation works on first boot. No GPU, no display server to configure, no extra setup.

Process management: s6-overlay v3 supervises OpenCode and Xvfb. Either crashes, s6 restarts it automatically. Your container restart policy stays clean.

Persistence

All OpenCode data lives under /home/opencode inside the container. The compose file maps that to ./data/opencode on your host:

volumes:
  - ./data/opencode:/home/opencode

That one bind mount covers everything: sessions, settings, MCP configs, plugins, tool history, cache. Rebuild the container, update to a new image, or move to a different machine. Your state comes back.

This is a bind mount, not a named volume. That means you can browse the files directly, back them up, or rsync them to another machine. docker compose down -v does not touch them.

Claude Auth Plugin: Use Your Subscription Instead of an API Key

If you have Claude Max or Pro, you're already paying for Claude access. You don't need to pay for a separate API key on top of that.

Enable the Claude Auth plugin with one env var:

environment:
  - ENABLE_CLAUDE_AUTH=true

The plugin reads credentials from ./data/opencode/.claude/.credentials.json. Log in once, the credentials persist via the bind mount, and the plugin picks them up on every restart. No API key needed, no extra billing.

Toggle off by removing the env var and restarting.

Note: This may be outside what Anthropic's terms of service cover. The README calls this out. Make your own call.

oh-my-openagent: Turn OpenCode Into a Multi-Agent System

HolyCode ships with optional support for oh-my-openagent, a multi-agent orchestration plugin for OpenCode. Enable it the same way as Claude Auth:

environment:
  - ENABLE_OH_MY_OPENAGENT=true

It installs automatically on first boot and activates on restart. No manual setup.

What it does: parallel execution, specialized agents, background tasks. Instead of a single agent working through your request sequentially, oh-my-openagent coordinates multiple agents running in parallel, each focused on a specific part of the problem.

Toggle it off by removing the env var and restarting. Everything else in HolyCode stays exactly the same.

Provider Support

OpenCode is not locked to one provider. HolyCode exposes environment variables for every supported provider:

Provider	Variable
Anthropic	`ANTHROPIC_API_KEY`
OpenAI	`OPENAI_API_KEY`
Google Gemini	`GEMINI_API_KEY`
Groq	`GROQ_API_KEY`
AWS Bedrock	`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`
Azure OpenAI	`AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_API_VERSION`
GitHub Models	`GITHUB_TOKEN`

Set the keys for the providers you use. Ignore the rest.

HolyCode Cloud

Don't want Docker? HolyCode Cloud is coming.

Same tools. Same conversation history. Synced state across any device. Open a browser on your laptop, your tablet, anywhere, and pick up exactly where you left off. No Docker, no compose file, no terminal required.

Early access is free: https://holycode.coderluii.dev/cloud

How I Run Claude Code in Docker with a Web UI and Headless Browser

CoderLuii — Sun, 22 Mar 2026 04:42:44 +0000

You know the drill. You want Claude Code on a server. In a browser. With Playwright so it can actually interact with web pages. With every AI CLI you might need. With TypeScript, Python, database clients, the works.

So you start installing things.

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 Claude Code's installer hangs silently because WORKDIR is root-owned. Then SQLite locks on your NAS mount.

Two hours later you haven't written a single line of code.

I got tired of doing this on every new server. So I built a container that handles all of it, and I ran it on my own server daily until every edge case surfaced and got fixed. That container is HolyClaude. It's free and open source, MIT license.

getting it running

Create a folder, drop in a compose file, pull, start.

mkdir holyclaude && cd holyclaude

Here's the compose file:

services:
  holyclaude:
    image: coderluii/holyclaude:latest
    container_name: holyclaude
    ports:
      - "3001:3001"
    volumes:
      - ./data/claude:/home/claude/.claude
      - ./workspace:/workspace
    environment:
      - TZ=UTC
    restart: unless-stopped
    shm_size: 2g
    cap_add:
      - SYS_ADMIN
      - SYS_PTRACE
    security_opt:
      - seccomp=unconfined

docker compose up -d

Open http://localhost:3001. Create a CloudCLI account (takes about 10 seconds), then sign in with your Anthropic credentials. You're in Claude Code, in your browser, with a headless browser ready to go.

That shm_size: 2g line is important. Chromium crashes without it because Docker allocates 64MB of shared memory by default. This is the number one issue people hit and the error messages don't point you anywhere useful.

how authentication works

HolyClaude runs the real Claude Code CLI from Anthropic. Not a wrapper, not a proxy. Your existing account works directly.

If you're on the Max or Pro plan, sign in through CloudCLI. It's the same OAuth flow as desktop Claude Code. Your subscription works as-is. If you prefer API keys, paste your Anthropic API key in the web UI. Pay-per-use, same billing.

Your credentials live in ./data/claude/ on your host. The container doesn't intercept or proxy anything.

the headless browser situation

This is the part that takes the most work to get right in Docker. Here's what HolyClaude handles for you:

Chromium needs more than 64MB of shared memory. It needs a virtual display, so Xvfb has to be configured at :99 and start before Chromium. It needs specific sandbox flags for running in a container. Playwright needs to find the system Chromium instead of trying to download its own copy.

When you ask Claude to take a screenshot, run Playwright tests, fill out a form, or scrape a site, it works. Because all of this is already configured.

process management

The container runs multiple services: Xvfb, the web UI server, file watchers. A shell script loop won't handle restarts cleanly or guarantee startup order.

I'm using s6-overlay. It gives proper dependency ordering (Xvfb starts before anything that needs a display), auto-restart on crash, and clean shutdown when you run docker compose down. It's what Linuxserver.io uses in their images, and for good reason.

image variants

The full image is about 4GB because it bundles Chromium, Playwright, and a full dev toolchain. If you don't need the browser stuff, the slim tag is about 2GB.

docker pull coderluii/holyclaude:latest
docker pull coderluii/holyclaude:slim

Both are multi-arch. AMD64 and ARM64. Works on Linux, macOS with Docker Desktop, Windows with WSL2, and Synology/QNAP NAS.

what I actually use it for

Long-running Claude Code sessions on my home server. I close my laptop and come back the next day. Session is still there.

Browser automation. I ask Claude to screenshot a URL, run tests, interact with a page. Chromium is ready. I don't configure anything.

Multi-model comparison. Claude, Gemini, and Codex are all in the same environment. Useful when I want to see how each handles a task on the same codebase.

Everything persists in ./data/. Files, auth, configs, state. Upgrade the container and nothing changes.

things it doesn't do

No built-in HTTPS. Put it behind Caddy, Traefik, or nginx if you're exposing it outside localhost. No multi-user access control. CloudCLI is a third-party web UI, not the official Anthropic desktop app.

troubleshooting the common stuff

If Chromium crashes, check shm_size: 2g in your compose file. If file changes aren't detected on a NAS mount, add CHOKIDAR_USEPOLLING=true.

if you try it and hit something, open an issue on GitHub. free and open source, MIT license.

GitHub: https://github.com/CoderLuii/HolyClaude
Docker Hub: https://hub.docker.com/r/coderluii/holyclaude
Website: https://holyclaude.coderluii.dev