coderluii/holycode repository overview

⁠HolyCode ⚡

One container. Every tool. Any provider.

OpenCode AI coding agent with built-in web UI, Claude subscription support, 50+ dev tools, a sandboxed headless browser, optional Paperclip, and external CLIProxyAPI endpoint support. Use your existing Claude Max/Pro plan. No separate API key needed.

v1.2.2 refreshes selected bundled runtimes, CLIs, libraries, and container build inputs while keeping Paperclip 2026.831.1 on its compatible self-hosted behavior. Run openspec init --tools opencode inside a project when you want OpenSpec 1.13.1; HolyCode never initializes it at startup and disables OpenSpec telemetry in the image.

⁠Quick Start

Download the Chromium seccomp profile next to your Compose file:

mkdir -p config
curl -fsSLo config/chromium-seccomp.json \
  https://raw.githubusercontent.com/CoderLuii/HolyCode/v1.1.3/config/chromium-seccomp.json

services:
  holycode:
    image: coderluii/holycode:latest
    container_name: holycode
    restart: unless-stopped
    shm_size: 2g
    security_opt:
      - seccomp=./config/chromium-seccomp.json
    ports:
      - "4096:4096"
      # - "3100:3100" # Paperclip dashboard
    volumes:
      - ./data/opencode:/home/opencode
      - ./local-cache/opencode:/home/opencode/.cache/opencode
      - ./workspace:/workspace
    environment:
      - ANTHROPIC_API_KEY=your-key-here
      # - ENABLE_PAPERCLIP=true
      # - PAPERCLIP_BIND=lan
      # - PAPERCLIP_ALLOWED_HOSTNAMES=192.168.1.50,my-host.local

docker compose up -d
# Open http://localhost:4096

That's it. Open your browser and start building.

⁠What's Inside

🤖 OpenCode AI Agent — Built-in web UI on port 4096. Provider-agnostic. Bring any API key.

🔑 Claude Subscription Support — Use your existing Claude Max/Pro plan with OpenCode. No separate API key. Toggle with ENABLE_CLAUDE_AUTH=true.

🧠 Bring Your Own Multi-Agent Plugin — HolyCode-managed oh-my-openagent installation is currently suspended. The first flag-free start disables the old managed entry while keeping its settings, skills, and package cache.

🌐 Headless Browser — Chromium + Xvfb + Playwright, pre-configured for screenshots, scraping, and browser automation.

🛠️ 50+ Dev Tools: Node.js 24.21.0 LTS with npm 12.0.2, Python 3.13 on Trixie, OpenCode 1.18.31, OpenSpec 1.13.1, Paperclip 2026.831.1, eza 0.23.5, fzf 0.74.4, lazygit 0.65.1, pnpm 12.4.2, tsx 4.23.13, Vite 8.3.0, ESLint 10.10.0, Prettier 3.9.8, Wrangler 4.134.0 with Miniflare 5.20260917.0-alpha and workerd 1.20260917.1, Prisma 7.10.0, Lighthouse 13.4.1, Playwright 1.63.0, pandas 3.0.6, Matplotlib 3.11.2, tqdm 4.70.1, FastAPI 0.141.1, Uvicorn 0.53.0, Claude stable 2.1.276, TypeScript 6.0.3, NumPy 2.5.3, json-server 0.17.4, git, ripgrep, bat, delta, gh CLI 2.101.0, and more.

TypeScript stays on 6.0.3 because TypeScript 7 removes the tsserver command and changes the stable programmatic API surface. Prisma stays on stable 7.10.0 instead of the 8.0 release candidate, and json-server stays on stable 0.17.4 instead of the 1.0 beta. Netlify CLI, serve, Vercel, sharp-cli, concurrently, and LHCI are not bundled. Wrangler's removed legacy_env mode is not supported.

🧩 Bundled Services — Optional Paperclip on port 3100. Hermes is temporarily unbundled while upstream dependency fixes land; existing .hermes data is preserved. CLIProxyAPI integration remains available for an externally managed endpoint.

🤝 10+ AI Providers — Anthropic, OpenAI, Gemini, Groq, AWS Bedrock, Azure OpenAI, Vertex AI, GitHub Models, Ollama, and any OpenAI-compatible endpoint.

⚙️ s6-overlay v3 — Process supervision with auto-restart and clean shutdown. No zombie processes.

💾 Persistent State — One bind mount. Sessions, settings, MCP configs, plugins all survive rebuilds.

🔒 Permissions — UID/GID remapping via PUID/PGID. No credentials are baked into the image; optional integrations use the local env vars and mounts you configure.

⁠Environment Variables

Paperclip defaults to authenticated mode with the lan bind preset inside HolyCode so it can bind to 0.0.0.0 and still pass upstream doctor checks in Docker.

Paperclip runs with HOME=/home/opencode and XDG paths under /home/opencode, matching the OpenCode web service. Keep your main state mount at /home/opencode so Paperclip's OpenCode workers read the same config as the web UI.

Paperclip now ships its Skills catalog through the package set HolyCode installs, so the Skills page loads without a HolyCode compatibility shim.

Set PAPERCLIP_ALLOWED_HOSTNAMES only for trusted LAN/private hostnames or IPs. Restart after changing it; hostname guard and authentication remain enabled.

Hermes is temporarily not bundled. Remove ENABLE_HERMES=true from older deployments before starting the current image. HolyCode leaves /home/opencode/.hermes untouched for a future restored integration or an externally managed Hermes instance.

HolyCode-managed oh-my-openagent installation is currently suspended. With ENABLE_OH_MY_OPENAGENT=true, startup stops without changing plugin state. Remove the flag and the first successful start disables the old active entry, records its package spec, and preserves its settings, skills, and package cache. A manually added plugin is user-managed and outside the image's release validation.

CLIProxyAPI support is disabled by default and targets an externally managed endpoint. HolyCode does not bundle the sidecar until its release binaries have verifiable compiler provenance and pass govulncheck. The integration still adds a separate cliproxyapi provider without changing ENABLE_CLAUDE_AUTH, opencode-claude-auth, or /home/opencode/.claude.

⁠Updates and Audit Notes

When upgrading from a release before v1.1.3, download the Chromium seccomp profile and add it to the holycode service before recreating the container:

mkdir -p config
curl -fsSLo config/chromium-seccomp.json \
  https://raw.githubusercontent.com/CoderLuii/HolyCode/v1.1.3/config/chromium-seccomp.json

security_opt:
  - seccomp=./config/chromium-seccomp.json

Then update with:

docker compose stop
# Back up the home, cache, and workspace volumes with your host backup tool.
docker compose pull
docker compose up -d

v1.2.2 keeps Paperclip at 2026.831.1, so this release adds no Paperclip migration or native-runner default override. Roll back by restoring untouched pre-upgrade home, cache, and workspace volumes with image 1.2.1; do not reuse volumes that the newer image has already started against for the rollback check.

v1.1.9 upgrades Paperclip from 2026.824.1 to 2026.831.1 with migrations 0223 through 0230. The retired brandColor and attachmentMaxBytes fields are removed, and in-progress login sessions reset. Keep an untouched pre-upgrade backup and restart login after the upgrade. Roll back only by restoring that backup with image 1.1.8; do not point 1.1.8 at data already migrated by 1.1.9.

v1.1.4 upgrades Paperclip from 2026.707.0 to 2026.722.0. Keep untouched pre-upgrade copies of your volumes until onboarding, Skills, agents, connections, and normal provider work pass. Roll back only by restoring those copies with image 1.1.3; do not point 1.1.3 at Paperclip data already migrated by 1.1.4.

Tagged images pin direct npm, PyPI, and GitHub-release versions. Binary assets use checksums, container bases use digests, and GitHub Actions use commit SHAs. Claude Code is pinned to @anthropic-ai/[email protected]. The supported Claude Auth plugin is included as an integrity-verified offline payload. Python packages use a hash-locked requirements file and an offline packaging-tool seed. npm lifecycle scripts are disabled during installation and validated by exact package version, integrity, architecture, and script body before approved scripts run. Debian packages resolve from current Trixie repositories at build time. User-installed plugins remain outside the image SBOM. HolyCode publishes per-platform SBOM and provenance attestations and runs per-platform vulnerability scans without claiming byte-for-byte reproducibility, universal freshness, or zero total findings.

⁠Links

• GitHub⁠
• HolyCode Page⁠
• HolyCode Cloud (early access)⁠
• Full Documentation⁠
• Podman Guide⁠