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

HolyCode

Ein Container. Alle Werkzeuge. Jeder Anbieter.

OpenCode läuft in einem Container mit allem bereits installiert. 50+ Entwicklungswerkzeuge, 10+ KI-Anbieter, headloser Browser, persistenter Zustand. Lege es auf einem beliebigen Rechner ab und mach genau dort weiter, wo du aufgehört hast.

Funktioniert mit deinem Claude-Abonnement. Aktiviere das Claude Auth-Plugin und nutze deinen bestehenden Claude Max/Pro-Plan. Kein separater API-Schlüssel nötig.

Mehragenten-Plugin vorerst selbst verwalten. Die von HolyCode verwaltete Installation von oh-my-openagent ist in v1.1.4 ausgesetzt. Beim ersten erfolgreichen Start ohne das alte Flag wird der frühere verwaltete Plugin-Eintrag deaktiviert; Einstellungen, Skills und Paket-Cache bleiben erhalten.

Du wolltest eine Stunde damit verbringen, deine Umgebung wiederherzustellen. Oder du kannst einfach docker compose up ausführen.

Kein Self-Hosting gewünscht? HolyCode Cloud kommt. Dieselben Werkzeuge, null Einrichtung. Frühzugang ist kostenlos.

Was ist das?

Du kennst die Geschichte. Du richtest deine Entwicklungsumgebung perfekt ein. Dann wechselst du den Rechner. Oder baust einen Container neu auf. Oder dein System entscheidet, dass heute der Tag ist, an dem es stirbt.

Plötzlich installierst du Werkzeuge neu. Suchst nach Konfigurationsdateien. Gibst API-Schlüssel erneut ein. Fragst dich, warum ripgrep nicht mehr im PATH ist. Versuchst herauszufinden, warum Chromium nicht startet, weil Docker Containern 64 MB gemeinsamen Speicher gibt. Dann ist Xvfb nicht konfiguriert. Dann stimmt die UID im Container nicht mit der des Hosts überein und alles gibt Permission denied.

HolyCode ist der Container, den ich gebaut habe, nachdem ich jeden einzelnen dieser Probleme gelöst hatte.

Er kapselt OpenCode, einen KI-Programmieragenten mit eingebautem Web-UI. Alle deine Einstellungen, Sitzungen, MCP-Konfigurationen, Plugins und Werkzeugverlauf leben in einem Bind-Mount außerhalb des Containers. Neu aufbauen, aktualisieren oder auf einen neuen Rechner umziehen. Dein Zustand kommt sofort zurück.

Es ist die gleiche Idee wie HolyClaude, aber OpenCode statt Claude Code kapselnd. Und hier ist der Punkt: OpenCode ist nicht an einen einzigen Anbieter gebunden. Weise es auf Anthropic, OpenAI, Google Gemini, Groq, AWS Bedrock oder Azure OpenAI. Gleicher Container, deine Wahl des Modells.

50+ Entwicklungswerkzeuge, zwei Sprachlaufzeiten, ein headloser Browser-Stack und Prozessüberwachung. Alles verkabelt, alles beim ersten Start bereit. Ich betreibe das auf meinem eigenen Server. Jeder Fehler wurde gefunden, diagnostiziert und behoben.

Du lädst es herunter. Du startest es. Du öffnest den Browser. Du baust.

Inhaltsverzeichnis

🚀 Schnellstart

Schritt 1. Lade das Image herunter.

docker pull coderluii/holycode:latest

Schritt 2. Erstelle eine docker-compose.yaml.

Das Compose-Setup verwendet das Chromium-seccomp-Profil von HolyCode. Wenn du nicht aus einem Repository-Klon arbeitest, lade zuerst die Release-Datei herunter:

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"
    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

Schritt 3. Starte es.

docker compose up -d

Öffne http://localhost:4096. Du bist drin.

Die mitgelieferte docker-compose.yaml verwendet die Syntax ${ANTHROPIC_API_KEY}, die aus deiner Shell-Umgebung oder einer .env-Datei liest. Kopiere .env.example nach .env und trage deinen API-Schlüssel ein.

nach oben

☁ HolyCode Cloud (Demnächst)

Kein Self-Hosting gewünscht? Wir bauen eine verwaltete Version von HolyCode.

Die gleichen 50+ Werkzeuge. Die gleichen 10+ Anbieter. Der gleiche persistente Zustand. Kein Docker. Kein Terminal. Öffne einfach deinen Browser und programmiere.

Was du mit Cloud bekommst:

• Null Einrichtung. Kein Docker, keine Konfigurationsdateien, keine Terminalbefehle.
• Funktioniert auf jedem Gerät. Laptop, Tablet, Smartphone. Öffne einen Browser und los.
• Getaggte Releases aktualisieren OpenCode und die Tool-Pins für dich.
• Dein Zustand folgt dir. Sitzungen, Einstellungen, MCP-Konfigurationen zwischen Nutzungen gespeichert.

Der Frühzugang ist kostenlos. Keine Kreditkarte erforderlich.

Sichere deinen Platz

nach oben

💻 Plattformunterstützung

nach oben

⚡ Warum HolyCode

Ich habe das gebaut, weil ich es leid war, jedes Mal das gleiche Setup zu wiederholen. OpenCode installieren, einen headlosen Browser einrichten, Berechtigungsprobleme beheben, Prozessüberwachung debuggen. Jedes. Mal.

Also habe ich einen Container gemacht, der das alles erledigt. Und dann habe ich jeden möglichen Fehler getroffen, damit du es nicht musst.

nach oben

🤖 Anbieterunterstützung

OpenCode ist anbieterunabhängig. Setze den API-Schlüssel, den du verwendest, und fertig.

Du musst nur Schlüssel für Anbieter setzen, die du tatsächlich verwendest. Alles andere ist optional und wird ignoriert.

Vertex AI, GitHub Models und Ollama werden über das Anbietersystem von OpenCode konfiguriert. Führe opencode providers login im Container aus.

nach oben

📋 Docker Compose - Schnell

Die minimale Einrichtung. Kopieren, Schlüssel eintragen, ausführen.

services:
  holycode:
    image: coderluii/holycode:latest
    container_name: holycode
    restart: unless-stopped
    shm_size: 2g              # Erforderlich für Chromium-Stabilität
    ports:
      - "4096:4096"           # OpenCode Web-UI
    volumes:
      - ./data/opencode:/home/opencode
      - ./local-cache/opencode:/home/opencode/.cache/opencode
      - ./workspace:/workspace  # Deine Projektdateien
    environment:
      - PUID=1000
      - PGID=1000
      - ANTHROPIC_API_KEY=your-key-here  # Oder durch beliebigen Anbieterschlüssel ersetzen

nach oben

📄 Docker Compose - Vollständig

Jede Option dokumentiert. In docker-compose.yaml kopieren und auskommentieren, was benötigt wird.

# 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:
      # --- Persistent state (all OpenCode data under home dir) ---
      - ./data/opencode:/home/opencode   # Config, sessions, plugins, all XDG paths

      # --- Cache isolation (keeps plugin cache on local disk, avoids CIFS/SMB symlink issues) ---
      - ./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
      # - [email protected]

      # --- 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

      # --- Legacy oh-my-openagent flag ---
      # Managed installation is unavailable in v1.1.4. Existing config is preserved.
      # Startup stops with a migration message while this flag is true.
      # - ENABLE_OH_MY_OPENAGENT=true

nach oben

🔧 Umgebungsvariablen

ENABLE_CLAUDE_AUTH wird beim Neustart des Containers wirksam. ENABLE_OH_MY_OPENAGENT ist nur noch eine veraltete Einstellung und beendet derzeit den Start mit einem Migrationshinweis.

HOLYCODE_PLUGIN_UPDATE steuert Plugin-Paketaktualisierungen. manual (Standard) installiert aktivierte Plugins nur wenn sie fehlen und behält vom Benutzer installierte Versionen bei. auto installiert fehlende Plugins und synchronisiert die deklarierten Pins beim Start. Dies ist unabhängig von OPENCODE_DISABLE_AUTOUPDATE, das nur OpenCode betrifft.

HolyCode installiert oh-my-openagent derzeit nicht. Wenn ENABLE_OH_MY_OPENAGENT=true in einer älteren Installation bestehen bleibt, stoppt der Container ohne Änderungen. Nach dem Entfernen des Flags deaktiviert der erste erfolgreiche Start den alten aktiven Eintrag und erhält Einstellungen, Skills und Paket-Cache.

ENABLE_PAPERCLIP=true startet Paperclip auf Port 3100 im Container. Öffne das Dashboard, erstelle ein Unternehmen und stelle dort OpenCode-gestützte Agenten ein. Paperclip persistiert automatisch unter ~/.paperclip.

Hermes ist im aktuellen Image weiterhin nicht gebündelt. Wenn ENABLE_HERMES=true aus einer älteren Installation bestehen bleibt, beendet HolyCode den Start mit einem kurzen Migrationshinweis. /home/opencode/.hermes bleibt unverändert erhalten, damit die Daten nach einer späteren Wiederaufnahme der Integration oder bei einem Rollback verfügbar sind.

GIT_USER_NAME und GIT_USER_EMAIL werden nur beim ersten Start angewendet. Zum erneuten Anwenden die Sentinel-Datei löschen und neu starten: docker exec holycode rm /home/opencode/.config/opencode/.holycode-bootstrapped dann docker compose restart.

nach oben

📦 Was ist enthalten

nach oben

🧩 Integrierte Dienste

Paperclip bleibt als optionaler Dienst über OpenCode gebündelt. Die CLIProxyAPI-Integration verwendet weiterhin einen extern verwalteten Endpunkt. Hermes ist vorübergehend nicht im Image enthalten.

Hermes Agent (vorübergehend nicht gebündelt)

Hermes bleibt aus dem Image entfernt. HolyCode startet keinen Hermes-Prozess und veröffentlicht keinen Hermes-Port.

Deine vorhandenen Daten unter /home/opencode/.hermes werden weder gelöscht noch migriert. Entferne ENABLE_HERMES=true aus älteren Konfigurationen, damit das aktuelle Image startet. Bewahre das Verzeichnis für eine spätere Wiederaufnahme der Integration oder für die Wiederherstellung eines unveränderten Vorab-Snapshots auf.

Paperclip

Paperclip ist die Option "Agenten-Board". Es gibt dir ein lokales Dashboard auf Port 3100, wo du ein Unternehmen erstellst, Agenten einstellst und diese Agenten nach Zeitplan aufwachen lässt. Im Hintergrund werden opencode run-Prozesse gestartet, also sind die Arbeiter immer noch HolyCode.

Aktivieren mit:

environment:
  - ENABLE_PAPERCLIP=true
  - PAPERCLIP_PORT=3100

Der Paperclip-Zustand liegt unter /home/opencode/.paperclip. Paperclip läuft ebenfalls mit /home/opencode als Home und hält OpenCode-Konfiguration, Cache und Status unter demselben Verzeichnis, sodass die Agenten dieselbe persistente Konfiguration sehen wie die OpenCode-Web-UI. Paperclip liefert den Skills-Katalog jetzt über das Paketset aus, das HolyCode installiert, sodass die Skills-Seite den Katalog lädt statt bei GET /api/skills/catalog zu scheitern. Öffne das Dashboard, richte dein Unternehmen ein und stelle dort OpenCode-gestützte Mitarbeiter ein.

nach oben

🏗 Architektur

graph TD
    A[docker compose up -d] --> B[entrypoint.sh]
    B --> C[UID/GID Remap]
    C --> D[Plugin 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]
    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]

Der Einstiegspunkt verwaltet Benutzer-Remapping, Plugin-Umschalter, optionale integrierte Dienst-Umschalter und die Erststart-Einrichtung. s6-overlay überwacht Xvfb, den OpenCode-Webserver und alle aktivierten optionalen integrierten Dienste. Bei einem Absturz eines überwachten Prozesses startet s6 ihn automatisch neu. Greife auf das Web-UI auf Port 4096 zu oder führe Befehle im Container aus für die vollständige CLI-Erfahrung.

nach oben

💻 CLI-Verwendung

Das Web-UI auf Port 4096 ist die primäre Schnittstelle. Du kannst OpenCode aber auch direkt von der Kommandozeile im Container verwenden.

Interaktives TUI

docker exec -it holycode bash
opencode

Dies öffnet OpenCodes vollständiges Terminal-UI mit denselben Funktionen wie die Web-Version.

Einmalige Befehle

Führe einen einzelnen Prompt aus ohne das TUI zu betreten:

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

Mit dem laufenden Server verbinden

Verbinde eine lokale TUI-Sitzung mit dem bereits laufenden OpenCode-Webserver:

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

Dies teilt dieselbe Sitzung wie das Web-UI. Änderungen in einem erscheinen im anderen.

Anbieterverwaltung

Anbieter von innerhalb des Containers auflisten und konfigurieren:

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

oh-my-openagent Migration

HolyCode installiert oder aktualisiert oh-my-openagent in v1.1.4 nicht. Mit ENABLE_OH_MY_OPENAGENT=true stoppt der Start, ohne den Plugin-Zustand zu ändern. Nach dem Entfernen des Flags deaktiviert der erste erfolgreiche Start den alten Eintrag, speichert dessen Paketangabe und erhält Einstellungen, Skills und Paket-Cache. Fügst du das Plugin später manuell wieder hinzu, behandelt HolyCode es als benutzerverwaltet.

Nützliche Befehle

nach oben

💾 Daten und Persistenz

Der gesamte OpenCode-Zustand lebt in einem einzigen Bind-Mount unter ./data/opencode. Der Container ist zustandslos. Der Bind-Mount enthält alles, was wichtig ist.

Den Container jederzeit neu erstellen. docker compose pull && docker compose up -d ausführen und Sitzungen, Einstellungen und Konfigurationen kommen automatisch zurück.

SQLite WAL-Hinweis. Die Sitzungsdatenbank verwendet Write-Ahead Logging. Die .db-Datei nicht kopieren, während der Container läuft. Den Container zuerst stoppen, wenn die Datenbankdatei gesichert oder migriert werden muss.

Netzwerkspeicher-Hinweis. Wenn sich ./data/opencode auf einem CIFS/SMB-Netzwerk-Mount (NAS, Synology, TrueNAS) befindet, kann der SQLite WAL-Modus fehlschlagen, da SMB standardmäßig kein Byte-Range-Locking unterstützt. HolyCode erkennt dies beim Start und gibt eine Warnung mit dem Fix aus. Siehe den Abschnitt Fehlerbehebung unten.

nach oben

🔐 Berechtigungen

HolyCode verwendet PUID und PGID, um den internen Container-Benutzer dem Host-Benutzer anzupassen. Das bedeutet, dass Dateien, die in ./workspace geschrieben werden, dir gehören, nicht root.

Finde deine IDs auf Linux und macOS:

id -u   # PUID
id -g   # PGID

Auf den meisten Systemen ist das 1000:1000. Auf macOS ist es oft 501:20. Im Compose-File eintragen:

environment:
  - PUID=501
  - PGID=20

Wenn du das weglässt, können Dateien in deinem Workspace root gehören und du brauchst sudo, um sie vom Host aus zu bearbeiten.

nach oben

⬆️ Aktualisierungen

Stoppe den Container und sichere die Home-, Cache- und Workspace-Volumes, bevor du das neueste Image herunterlädst.

Wenn du von einer Version vor v1.1.3 aktualisierst, lade das oben gezeigte seccomp-Profil herunter und füge security_opt zum Dienst holycode hinzu, bevor du den Container neu erstellst.

v1.2.9 behält Paperclip 2026.831.1 bei, daher gibt es keine neue Paperclip-Migration und keine neue Standardüberschreibung für den nativen Runner. Stelle für ein Rollback die unveränderten Home-, Cache- und Workspace-Volumes von vor dem Upgrade mit Image 1.2.8 wieder her; verwende keine Volumes, die bereits mit v1.2.9 gestartet wurden.

v1.1.9 migriert Paperclip von 2026.824.1 auf 2026.831.1 mit den Migrationen 0223–0230. Die entfernten Felder brandColor und attachmentMaxBytes werden gelöscht und laufende Anmeldesitzungen zurückgesetzt; melde dich nach dem Upgrade erneut an. Stelle für ein Rollback das unveränderte Backup mit Image 1.1.8 wieder her. Starte 1.1.8 niemals mit einer bereits von v1.1.9 migrierten Datenbank.

Paperclip wird in v1.1.4 von 2026.707.0 auf 2026.722.0 migriert. Ein Rollback ist nur mit Image 1.1.3 und unveränderten Volumes von vor dem v1.1.4-Upgrade möglich. Starte Image 1.1.3 niemals mit bereits von v1.1.4 migrierten Paperclip-Daten.

docker compose stop
docker compose pull
docker compose up -d

nach oben

🛠 Fehlerbehebung

services:
  holycode:
    shm_size: 2g

id -u && id -g

environment:
  - PUID=1001   # durch tatsächliche UID ersetzen
  - PGID=1001   # durch tatsächliche GID ersetzen

ports:
  - "4097:4096"   # Zugriff über http://localhost:4097

# Linux / macOS
lsof -i :4096

# Windows
netstat -ano | findstr :4096

docker compose logs -f holycode

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

Failed to run the query 'PRAGMA journal_mode = WAL'

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

# Nachher (nobrl,mfsymlinks hinzufügen)
//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

nach oben

🔨 Lokale Erstellung

Das Repository klonen, das Image erstellen, in der Compose-Datei ersetzen.

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

Dann in der docker-compose.yaml das Image ersetzen:

image: holycode:local

nach oben

🤝 Mitwirken

1. Das Repository forken
2. Einen Branch erstellen: git checkout -b feature/your-feature
3. Änderungen committen: git commit -m "feat: your feature"
4. Pushen: git push origin feature/your-feature
5. Einen Pull Request öffnen

Siehe CONTRIBUTING.md für vollständige Richtlinien.

nach oben

⭐ Support

Wenn HolyCode dir eine weitere Stunde Umgebungseinrichtung erspart hat, hier ist wie du es weitergeben kannst.

• Das Repository auf GitHub mit einem Stern versehen
• Mit jemandem teilen, der es nützlich finden würde
• Buy Me A Coffee
• PayPal
• GitHub Sponsors

nach oben

📄 Lizenz

MIT-Lizenz - siehe LICENSE.

nach oben