Looking for the hosted HolyCode option? Visit holycode.cloud.

OpenCode, self-hosted.Ready to run.

One Docker container with persistent state, developer tools, provider choice, and an optional Paperclip board.

Released v1.2.5 for amd64 and arm64.

Compose configurator

Source-backed configuration

Configure install
Provider

Set ANTHROPIC_API_KEY on the host before starting Compose.

Plugin updates
services:
  holycode:
    image: coderluii/holycode:1.2.5
    container_name: holycode
    restart: unless-stopped
    shm_size: 2g
    ports:
      - "127.0.0.1:4096:4096"
    security_opt:
      - seccomp=./config/chromium-seccomp.json
    volumes:
      - ./data/opencode:/home/opencode
      - ./local-cache/opencode:/home/opencode/.cache/opencode
      - ./workspace:/workspace
    environment:
      - "PUID=1000"
      - "PGID=1000"
      - "HOLYCODE_PLUGIN_UPDATE=manual"
      - "ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:-}"

Install the released image.

Pull the pinned image, keep the Chromium policy beside Compose, then open the local OpenCode service.

  1. Pull the image and policy

    Use the published tag for both the image and Chromium policy.

    mkdir -p config
    curl -fsSL https://raw.githubusercontent.com/CoderLuii/HolyCode/v1.2.5/config/chromium-seccomp.json -o config/chromium-seccomp.json
    docker pull coderluii/holycode:1.2.5
  2. Create compose.yaml

    Keep the local service bound to 127.0.0.1 and the three shipped volumes explicit. The configurator above produces the complete file.

    services:
      holycode:
        image: coderluii/holycode:1.2.5
        container_name: holycode
        restart: unless-stopped
        shm_size: 2g
        ports:
          - "127.0.0.1:4096:4096"
        security_opt:
          - seccomp=./config/chromium-seccomp.json
        volumes:
          - ./data/opencode:/home/opencode
          - ./local-cache/opencode:/home/opencode/.cache/opencode
          - ./workspace:/workspace
        environment:
          - "PUID=1000"
          - "PGID=1000"
          - "HOLYCODE_PLUGIN_UPDATE=manual"
          - "ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:-}"
  3. Start and open

    docker compose up -d

    Open http://localhost:4096 after the container starts. Keep ./local-cache/opencode on local disk. For CIFS or SMB mounts, use nobrl,mfsymlinks. The Podman guide covers rootless setup.

  4. Update with a snapshot

    docker compose stop
    # Snapshot ./data/opencode, ./local-cache/opencode, and ./workspace
    # Update the image and Chromium policy to the new release
    docker compose pull
    docker compose up -d

    A snapshot rollback restores untouched pre-upgrade volumes and starts the previous image. It does not claim an in-place database downgrade.

Pull the image and policy

mkdir -p config
curl -fsSL https://raw.githubusercontent.com/CoderLuii/HolyCode/v1.2.5/config/chromium-seccomp.json -o config/chromium-seccomp.json
docker pull coderluii/holycode:1.2.5

Everything the workstation brings.

The published image pins its runtime, tools, services and plugin behavior so the setup stays reviewable.

Runtime

Current tools inside the published image.

Node 24.21.0, npm 12.2.0, Python 3.13, OpenCode 1.18.34, Claude Code 2.1.290

Workstation

The useful parts are ready before first boot.

OpenCode AI agent, s6-overlay, persistent state, Chromium, Playwright and Xvfb. The 50+ tools include git, ripgrep, pnpm, TypeScript, Prisma, Lighthouse and ffmpeg. Vercel CLI, sharp-cli, concurrently and LHCI are not bundled.

Optional services

Enable only what the host needs.

Paperclip 2026.831.1 is optional on port 3100. OpenCode is bundled on port 4096.

Current limits

Release boundaries remain visible.

Claude auth plugin 2.2.1. HolyCode-managed oh-my-openagent installation is managed installation suspended. HOLYCODE_PLUGIN_UPDATE=manual is the default; HOLYCODE_PLUGIN_UPDATE=auto is explicit. Bundled Hermes is unavailable; migration data remains at /home/opencode/.hermes. CLIProxyAPI is external-only. Netlify CLI and serve are removed.

Bring the provider you already use.

Configure the credentials OpenCode expects. Switch supported providers without rebuilding the image.

Anthropic

Set the Anthropic API key OpenCode will use.

  • ANTHROPIC_API_KEY
OpenAI

Set the OpenAI API key OpenCode will use.

  • OPENAI_API_KEY
Gemini

Set the Gemini API key OpenCode will use.

  • GEMINI_API_KEY
Groq

Set the Groq API key OpenCode will use.

  • GROQ_API_KEY
AWS Bedrock

Provide AWS credentials and a region on the host.

  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY
  • AWS_REGION
Azure OpenAI

Provide the Azure endpoint, key, and API version on the host.

  • AZURE_OPENAI_ENDPOINT
  • AZURE_OPENAI_API_KEY
  • AZURE_OPENAI_API_VERSION

Also supported through OpenCode: Vertex AI, GitHub Models, Ollama, and OpenAI-compatible endpoints.

Data, updates, and known limits.

Your host keeps the volumes. HolyCode keeps the paths stable.

./data/opencode/home/opencode

/home/opencode/.claude/.credentials.jsonPersisted inside the home volume

./local-cache/opencode/home/opencode/.cache/opencode

./workspace/workspace

Update safely

Stop the stack, snapshot all three volumes, update the pinned image and policy, pull, then start. A snapshot rollback restores the previous image and untouched pre-upgrade volumes.

Chromium security warning for v1.2.5

Chromium scans for v1.2.5 still report five accepted upstream Chromium vulnerabilities, including two critical findings. Avoid untrusted browser content and automation until an upstream fix is available in a published image.

Read the v1.2.5 known issues

Stop rebuilding the same workstation.

HolyCode packages the setup that normally repeats across hosts: OpenCode, browser policy, permissions, process supervision and persistent paths.

I built it after repeating that setup and debugging the same host issues too many times. The released image keeps the moving parts in one reviewable place.

You still control

  • Provider credentials
  • Host updates
  • Volume snapshots
  • Published image selection
  • Current known issues

Before you install.

Short answers here. Maintained setup details stay in the project documentation.

Read the docs
Where does HolyCode store data?

Three host mounts keep the OpenCode home, local cache and workspace. Claude credentials persist inside the home volume at /home/opencode/.claude/.credentials.json.

Which providers work?

OpenCode supports Anthropic, OpenAI, Gemini, Groq, AWS Bedrock, Azure OpenAI and additional provider paths documented above.

How do plugin updates work?

manual is the default. Auto update is an explicit startup choice. HolyCode-managed oh-my-openagent installation remains suspended.

Is Paperclip required?

No. Paperclip is optional. Enable it only when you want the board on local port 3100.

What should I know about Chromium?

Keep the sandbox and release seccomp policy enabled. Read the current known issues before running browser automation.

Run HolyCode on your hardware.