DEV Community

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

Posted on

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

#docker #ai #devtools #programming

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
Enter fullscreen mode Exit fullscreen mode

Step 2. Start it:

docker compose up -d
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

Links

Top comments (0)