Make your Compose file

Choose a provider, decide whether to enable Paperclip, and save the generated file on your Docker host.

You need Docker with Compose and access to your chosen provider.

Set ANTHROPIC_API_KEY on the host before starting Compose.

Claude Auth plugin updates

Set provider credentials in your local environment. This page only creates placeholders.

compose.yaml

View complete Compose file
services:
  holycode:
    image: coderluii/holycode:1.3.0
    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:-}"

Paste the copied text into a new file named compose.yaml on your Docker host. Review it before starting the container.

Next: Set provider credentials

OpenCode uses local port 4096. Paperclip 2026.831.1 is off by default; enabling it adds local port 3100. Using Podman? Read the rootless setup guide.

Set your provider credentials

Set your chosen provider’s variables in the shell where you’ll run Docker Compose. The Compose file reads them at startup.

Anthropic

Set ANTHROPIC_API_KEY on the host before starting Compose.

  • ANTHROPIC_API_KEY
OpenAI

Set OPENAI_API_KEY on the host before starting Compose.

  • OPENAI_API_KEY
Gemini

Set GEMINI_API_KEY on the host before starting Compose.

  • GEMINI_API_KEY
Groq

Set GROQ_API_KEY on the host before starting Compose.

  • GROQ_API_KEY
AWS Bedrock

Set the AWS access key, secret key, and region on the host.

  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY
  • AWS_REGION
Azure OpenAI

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

  • AZURE_OPENAI_ENDPOINT
  • AZURE_OPENAI_API_KEY
  • AZURE_OPENAI_API_VERSION

Run it on your host

Keep compose.yaml and the config folder together. Set your provider variables locally before starting.

Get the image and Chromium policy

Save the policy as config/chromium-seccomp.json in the directory containing compose.yaml.

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

Start HolyCode

Run this from the directory containing compose.yaml.

docker compose up -d

After the container starts, open http://localhost:4096 on your host.

Keep your data through updates

HolyCode keeps its data, local cache and projects in three host folders.

On your hostInside HolyCode
Data and credentials./data/opencode/home/opencode
Local cache./local-cache/opencode/home/opencode/.cache/opencode
Projects./workspace/workspace

Credentials and cache

Claude credentials persist at /home/opencode/.claude/.credentials.json. Keep the cache on local disk. For CIFS or SMB mounts, use nobrl,mfsymlinks.

Back up before updating

Stop the stack. Snapshot all three volumes. Update the pinned image and matching Chromium policy, then pull, start and verify your workflows.

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

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

Before browser automation