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

OpenCode running in a container with everything already installed. 50+ dev tools, 10+ AI providers, headless browser, persistent state, and two serious upgrades on top: Hermes Agent and Paperclip. Drop it on any machine and pick up exactly where you left off.

Hermes Agent turns HolyCode into a meta-agent runtime. You get a smarter planning layer on top of OpenCode, an API surface on port 8642, MCP support, messaging adapters, and a clean way to let a "brain" delegate code work into the local container instead of bolting that together yourself.

Paperclip turns HolyCode into an agent board. You get a dashboard on port 3100 where you create a company, hire OpenCode-backed workers, wake them on heartbeat, and manage agent work from a real UI instead of hand-rolling scripts around opencode run.

Works with your Claude subscription. Enable the Claude Auth plugin and use your existing Claude Max/Pro plan. No separate API key needed.

Multi-agent orchestration built in. Enable oh-my-openagent and turn OpenCode into a coordinated agent system with parallel execution.

You were going to spend an hour getting your environment back. Or you could just docker compose up and get a coding workstation, a meta-agent, and an agent board in one shot.

Don't want to self-host? HolyCode Cloud is coming. Same tools, zero setup. Early access is free.

You know the drill. 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 because Docker gives containers 64MB of shared memory. Then Xvfb isn't configured. Then the UID inside the container doesn't match your host and everything is permission denied.

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

It wraps OpenCode, an AI coding agent with a built-in web UI. All your settings, sessions, MCP configs, plugins, and tool history live in a bind mount outside the container. Rebuild, update, or move to a new machine. Your state comes right back.

It's the same idea as HolyClaude but wrapping OpenCode instead of Claude Code. And here's the thing: OpenCode isn't locked to one provider. Point it at Anthropic, OpenAI, Google Gemini, Groq, AWS Bedrock, or Azure OpenAI. Same container, your choice of model.

50+ dev tools, two language runtimes, a headless browser stack, process supervision, and two bundled orchestration layers. All wired up, all ready on first boot. I've been running this on my own server. Every bug has been hit, diagnosed, and fixed.

You pull it. You run it. You open your browser. You build.

Step 1. Pull the image.

docker pull coderluii/holycode:latest

Step 2. 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
      - ./local-cache/opencode:/home/opencode/.cache/opencode
      - ./workspace:/workspace
    environment:
      - PUID=1000
      - PGID=1000
      - ANTHROPIC_API_KEY=your-key-here

In that example, /home/opencode is the fixed path inside the container. On the host, ./data/opencode and ./local-cache/opencode are just example bind-mount paths relative to the folder containing your docker-compose.yaml. You can replace them with any host paths you want.

Step 3. Start it.

docker compose up -d

Open http://localhost:4096. You're in.

The shipped docker-compose.yaml uses ${ANTHROPIC_API_KEY} syntax which reads from your shell environment or a .env file. Copy .env.example to .env and fill in your API key.

./data/opencode is only an example host path. If your compose file lives at /opt/holycode, that same bind mount becomes /opt/holycode/data/opencode on the host.

Keep ./local-cache/opencode on local disk. If this project folder lives on NAS/CIFS/SMB storage, change that cache mount to an absolute local host path instead.

back to top

Don't want to self-host? We're building a managed version of HolyCode.

Same 50+ tools. Same 10+ providers. Same persistent state. No Docker. No terminal. Just open your browser and code.

What you get with Cloud:

• Zero setup. No Docker, no config files, no terminal commands.
• Works on any device. Laptop, tablet, phone. Open a browser and go.
• Always updated. Latest OpenCode, latest tools. We handle it.
• Your state follows you. Sessions, settings, MCP configs saved between uses.

Early access is free. No credit card required.

Claim your spot

back to top

back to top

I built this because I was tired of re-doing the same setup every time. Installing OpenCode, wiring up a headless browser, 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.

back to top

OpenCode is provider-agnostic. Set whichever API key you use and you're done.

You only need to set keys for providers you actually use. Everything else is optional and ignored.

Vertex AI, GitHub Models, and Ollama are configured through OpenCode's provider system. Run opencode providers login inside the container.

back to top

The minimal setup. Copy, fill in your key, run.

services:
  holycode:
    image: coderluii/holycode:latest
    container_name: holycode
    restart: unless-stopped
    shm_size: 2g              # Required for Chromium stability
    ports:
      - "4096:4096"           # OpenCode web UI
    volumes:
      - ./data/opencode:/home/opencode
      - ./local-cache/opencode:/home/opencode/.cache/opencode
      - ./workspace:/workspace  # Your project files
    environment:
      - PUID=1000
      - PGID=1000
      - ANTHROPIC_API_KEY=your-key-here  # Or swap for any provider key

back to top

Every option documented. Copy to docker-compose.yaml and uncomment what you need.

# HolyCode - Full Configuration Reference
# Copy this file to docker-compose.yaml and customize.
# All options documented. Uncomment what you need.

services:
  holycode:
    image: coderluii/holycode:latest
    container_name: holycode
    restart: unless-stopped
    shm_size: 2g

    ports:
      - "4096:4096"   # OpenCode web UI

    volumes:
      # --- Main HolyCode data ---
      # Pick any host path you want here. This path maps to /home/opencode in the container.
      # It can live on local disk or network storage.
      - ./data/opencode:/home/opencode

      # --- Cache path ---
      # Keep this one on LOCAL disk for plugin/cache reliability.
      # If your main data path lives on NAS/CIFS/SMB, make this a separate local path.
      - ./local-cache/opencode:/home/opencode/.cache/opencode

      # --- Workspace ---
      - ./workspace:/workspace   # Your project files

    environment:
      # --- Container user ---
      - PUID=1000                # Match your host UID for file permissions
      - PGID=1000                # Match your host GID for file permissions

      # --- Git identity (used on first boot) ---
      # - GIT_USER_NAME=Your Name
      # - GIT_USER_EMAIL=you@example.com

      # --- AI provider API keys (add the ones you use) ---
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:-}
      # - OPENAI_API_KEY=${OPENAI_API_KEY:-}
      # - GEMINI_API_KEY=${GEMINI_API_KEY:-}
      # - GROQ_API_KEY=${GROQ_API_KEY:-}
      # - GITHUB_TOKEN=${GITHUB_TOKEN:-}

      # --- AWS Bedrock (uncomment all 3 for Bedrock) ---
      # - AWS_ACCESS_KEY_ID=
      # - AWS_SECRET_ACCESS_KEY=
      # - AWS_REGION=us-east-1

      # --- Azure OpenAI (uncomment all 3 for Azure) ---
      # - AZURE_OPENAI_ENDPOINT=
      # - AZURE_OPENAI_API_KEY=
      # - AZURE_OPENAI_API_VERSION=

      # --- OpenCode behavior (set by default in image, override if needed) ---
      # - OPENCODE_DISABLE_AUTOUPDATE=true
      # - OPENCODE_DISABLE_TERMINAL_TITLE=true
      # - OPENCODE_MODEL=claude-sonnet-4-6
      # - OPENCODE_PERMISSION=auto
      # - OPENCODE_DISABLE_LSP_DOWNLOAD=true
      # - OPENCODE_DISABLE_AUTOCOMPACT=true
      # - OPENCODE_ENABLE_EXA=true

      # --- Web UI Security (basic auth for opencode web) ---
      # - OPENCODE_SERVER_PASSWORD=your-password
      # - OPENCODE_SERVER_USERNAME=opencode

      # --- Claude Auth (use Claude subscription instead of API key) ---
      # Reads credentials from ./data/opencode/.claude/.credentials.json
      # NOTE: May violate Anthropic TOS. Use at your own risk.
      # Toggle on/off with docker compose down && up -d
      # - ENABLE_CLAUDE_AUTH=true

      # --- oh-my-openagent (multi-agent orchestration for OpenCode) ---
      # Enables the plugin through OpenCode config on container start
      # Toggle on/off with docker compose down && up -d
      # - ENABLE_OH_MY_OPENAGENT=true

back to top

Plugin toggles (ENABLE_CLAUDE_AUTH, ENABLE_OH_MY_OPENAGENT) take effect on container restart. Set the env var and run docker compose down && up -d.

HOLYCODE_PLUGIN_UPDATE controls plugin package updates. manual (default) installs enabled plugins only if they are missing. auto installs missing plugins and updates enabled plugins on every boot. This is separate from OPENCODE_DISABLE_AUTOUPDATE, which only affects OpenCode itself.

ENABLE_OH_MY_OPENAGENT=true enables the plugin through the main OpenCode config at /home/opencode/.config/opencode/opencode.json. On the host, that file appears under whatever host path you bind to /home/opencode. On boot, HolyCode also checks whether the plugin package is missing and installs it if needed.

ENABLE_OH_MY_OPENAGENT=true enables the plugin and exposes the built-in /oh-my-openagent-setup skill. The skill only appears when the plugin is enabled. Use it to create or update the plugin-specific config file at ~/.config/opencode/oh-my-openagent.jsonc.

ENABLE_PAPERCLIP=true starts Paperclip on port 3100 inside the container. Open the dashboard, create a company, then hire OpenCode-backed agents there. Paperclip persists under ~/.paperclip automatically.

HolyCode forces PAPERCLIP_DEPLOYMENT_MODE=authenticated by default because Paperclip's upstream local_trusted mode only allows loopback binding. In Docker, that would block port publishing on 0.0.0.0.

ENABLE_HERMES=true starts Hermes on port 8642 inside the container. Hermes persists under ~/.hermes, uses the already-installed opencode binary, and can expose an OpenAI-compatible API while delegating code work back into HolyCode.

Hermes is an API service, not a landing page. A 404 at http://localhost:8642/ is expected. The important signal is that the port is listening and the process stays healthy.

GIT_USER_NAME and GIT_USER_EMAIL are only applied on first boot. To re-apply, delete the sentinel file and restart: docker exec holycode rm /home/opencode/.config/opencode/.holycode-bootstrapped then docker compose restart.

back to top

back to top

HolyCode now ships with two optional layers on top of OpenCode. You do not need them to use the container. But if plain OpenCode gives you the hands, these two give you a brain and a control room.

• Hermes Agent is for when you want a smarter coordinator sitting above OpenCode.
• Paperclip is for when you want a board, a workflow, and actual agent management instead of just one-off prompts.

Flip the env var, restart the container, and the service comes up alongside the normal web UI.

Hermes is the "smarter brain" option. It runs as a bundled meta-agent, exposes an API service on port 8642, and delegates coding work by calling the local opencode binary that HolyCode already ships.

Why that matters:

• Planning above execution. OpenCode does the hands-on coding. Hermes gives you a layer that can reason, coordinate, and delegate down into that local worker.
• API-ready agent runtime. You can point other tooling at Hermes instead of wiring your own service around OpenCode.
• MCP and messaging in the same box. HolyCode already solves the dev-environment side. Hermes adds the "agent platform" layer on top.
• Persistent agent state. Its data lives under ~/.hermes, so rebuilds don't wipe the runtime you just configured.

If you want HolyCode to feel less like "a container with a coding tool" and more like "an AI runtime you can build systems on top of," Hermes is the part that changes that.

Turn it on with:

environment:
  - ENABLE_HERMES=true
  - HERMES_PORT=8642

Hermes state lives under /home/opencode/.hermes, so it follows the same persistence story as the rest of HolyCode.

Paperclip is the "agent board" option. It gives you a local dashboard on port 3100 where you create a company, hire agents, and let those agents wake up on schedule. Under the hood it spawns opencode run processes, so the workers are still HolyCode.

Why that matters:

• A real control surface. You stop treating agents like random shell commands and start treating them like a team with roles, tasks, and wake cycles.
• OpenCode-backed workers, not a toy layer. The board is Paperclip. The actual worker execution is still HolyCode doing real coding work.
• Faster delegation experiments. Create a company, assign work, and see how an agent workflow feels without building the orchestration stack yourself.
• Persistent board state. Data, config, storage, and embedded Postgres all live under ~/.paperclip.

If Hermes is the brain, Paperclip is the control room. It's the thing you turn on when you want to manage agent work, not just launch it.

Turn it on with:

environment:
  - ENABLE_PAPERCLIP=true
  - PAPERCLIP_PORT=3100
  - PAPERCLIP_DEPLOYMENT_MODE=authenticated

Paperclip state lives under /home/opencode/.paperclip. HolyCode bootstraps it in authenticated mode so Docker port publishing works cleanly. Open the dashboard, set up your company, and hire OpenCode-backed employees from there.

back to top

graph TD
    A[docker compose up -d] --> B[entrypoint.sh]
    B --> C[UID/GID Remap]
    C --> D[Plugin and Service Toggles]
    D --> E{First Boot?}
    E -->|Yes| F[bootstrap.sh]
    E -->|No| G[s6-overlay /init]
    F --> G
    G --> H[Xvfb :99]
    G --> I[opencode web :4096]
    G --> Q[Hermes API :8642]
    G --> R[Paperclip UI :3100]
    I --> J[Web UI]
    J --> K[Your Browser]
    I --> L[CLI Access]
    L --> M[docker exec -it holycode bash]
    M --> N[opencode TUI]
    M --> O[opencode run 'message']
    M --> P[opencode attach localhost:4096]
    Q --> S[Meta-agent API clients]
    R --> T[Agent board and CEO invite]

The entrypoint handles user remapping, plugin toggles, optional bundled-service toggles, and first-boot setup. s6-overlay supervises Xvfb, the OpenCode web server, and any optional bundled services you enabled. If a supervised process crashes, s6 restarts it automatically. Access the web UI at port 4096, Hermes on 8642, or Paperclip on 3100 when those services are enabled.

back to top

The web UI at port 4096 is the primary interface. But you can also use OpenCode directly from the command line inside the container.

docker exec -it holycode bash
opencode

This opens OpenCode's full terminal UI with all the same features as the web version.

Run a single prompt without entering the TUI:

docker exec -it holycode bash -c "opencode run 'explain this codebase'"

Connect a local TUI session to the already-running OpenCode web server:

docker exec -it holycode bash -c "opencode attach http://localhost:4096"

This shares the same session as the web UI. Changes in one appear in the other.

List and configure AI providers from inside the container:

docker exec -it holycode bash -c "opencode providers list"
docker exec -it holycode bash -c "opencode providers login"

If you enabled ENABLE_OH_MY_OPENAGENT=true, the /oh-my-openagent-setup skill becomes available. Use it to create or refresh the plugin-specific config:

/oh-my-openagent-setup

That flow is the supported path for:

• first-time oh-my-openagent setup
• reconfiguring after adding or removing providers
• restoring the intended picker defaults so only the primary agents are visible

HolyCode's default picker policy is:

• visible: sisyphus, hephaestus, prometheus, atlas
• hidden subagents: oracle, librarian, explore, metis, momus, multimodal-looker, sisyphus-junior

If you add a new provider later and the visible default model still looks stale, rerun /oh-my-openagent-setup, then run:

docker exec -it holycode bash -c "bunx oh-my-opencode doctor"
docker exec -it holycode bash -c "bunx oh-my-opencode refresh-model-capabilities"

HolyCode can guide the supported refresh path, but upstream OpenCode and oh-my-openagent model-resolution behavior still controls the final visible model state.

back to top

Most OpenCode state lives under /home/opencode inside the container. On the host, that data appears wherever you bind-mount /home/opencode. In the default examples below, the host path is ./data/opencode, but you can replace it with any path you want.

Plugin cache is mounted separately at ./local-cache/opencode by default so you can keep that cache path on local disk even if your main data path is somewhere else.

* These ./data/opencode/... paths are example host paths from the sample compose file. If you bind /home/opencode to a different host path, the same subdirectories will appear there instead.

Rebuild the container anytime. Run docker compose pull && docker compose up -d and your sessions, settings, and configs come back automatically.

SQLite WAL note. The sessions database uses Write-Ahead Logging. Don't copy the .db file while the container is running. Stop the container first if you need to back up or migrate the database file.

Network storage note. If ./data/opencode is on a CIFS/SMB network mount (NAS, Synology, TrueNAS), you need two mount options:

• nobrl — SQLite WAL mode requires this (byte-range locking workaround)
• mfsymlinks — plugin installation requires this (symlink support for node_modules)

Keep ./local-cache/opencode on local disk. If your whole HolyCode folder lives on network storage, change that cache mount to an absolute local host path such as /var/lib/holycode-cache/opencode:/home/opencode/.cache/opencode.

See the Troubleshooting section below.

back to top

HolyCode uses PUID and PGID to remap the internal container user to match your host user. This means files written to ./workspace are owned by you, not by root.

Find your IDs on Linux and macOS:

id -u   # PUID
id -g   # PGID

On most systems this is 1000:1000. On macOS it's often 501:20. Set them in your compose file:

environment:
  - PUID=501
  - PGID=20

If you skip this, files in your workspace may be owned by root and you'll need sudo to edit them from the host.

back to top

Pull the latest image and recreate the container. Your data stays untouched.

docker compose pull
docker compose up -d

That's it. One command. Your sessions, settings, and configs are in the bind mount so nothing is lost.

back to top

services:
  holycode:
    shm_size: 2g

id -u && id -g

environment:
  - PUID=1001   # replace with your actual UID
  - PGID=1001   # replace with your actual GID

ports:
  - "4097:4096"   # access via http://localhost:4097

# Linux / macOS
lsof -i :4096

# Windows
netstat -ano | findstr :4096

docker compose logs -f holycode

cap_add:
  - SYS_ADMIN
security_opt:
  - seccomp=unconfined

Failed to run the query 'PRAGMA journal_mode = WAL'

# Before
//192.168.1.100/share /mnt/share cifs credentials=/etc/smbcreds,uid=1000,gid=1000 0 0

# After — add nobrl and mfsymlinks
//192.168.1.100/share /mnt/share cifs credentials=/etc/smbcreds,uid=1000,gid=1000,nobrl,mfsymlinks 0 0

sudo umount /mnt/share
sudo mount /mnt/share

back to top

Clone the repo, build the image, swap it into your compose file.

git clone https://github.com/coderluii/holycode.git
cd holycode
docker build -t holycode:local .

Then in your docker-compose.yaml swap the image:

image: holycode:local

back to top

1. Fork the repo
2. Create a branch: git checkout -b feature/your-feature
3. Commit your changes: git commit -m "feat: your feature"
4. Push: git push origin feature/your-feature
5. Open a pull request

See CONTRIBUTING.md for full guidelines.

back to top

If HolyCode saved you from another hour of environment setup, here's how to pay it forward.

• Star the repo on GitHub
• Share it with someone who'd find it useful
• Buy Me A Coffee
• PayPal
• GitHub Sponsors

back to top

MIT License - see LICENSE.

back to top