48 KiB
🌍 English | Español | Français | Italiano | Português | Deutsch | Русский | हिन्दी | 中文 | 日本語 | 한국어
HolyClaude
Smetti di configurare. Inizia a costruire.
Un comando. Una workstation di sviluppo AI completa. Claude Code, interfaccia web, browser headless, 7 CLI AI, 50+ strumenti di sviluppo — containerizzati e pronti all'uso.
Avresti passato 2 ore a configurare tutto manualmente. Oppure puoi semplicemente fare docker compose up.
Funziona con il tuo abbonamento Claude Code esistente. Piano Max/Pro, chiave API — qualunque cosa tu abbia, funziona e basta.
Cos'è questo?
Lo sai com'è. Vuoi Claude Code. Ma lo vuoi anche nel browser. Con un browser headless per screenshot e test. Con Playwright configurato. Con tutte le CLI AI. Con TypeScript, Python, strumenti di deployment, client per database, GitHub CLI.
Allora cominci a installare le cose. Una per una. Poi Chromium non si avvia perché la memoria condivisa di Docker è 64MB. Poi Xvfb non è configurato. Poi l'UID all'interno del container non corrisponde al tuo host e tutto restituisce "permission denied". Poi ti accorgi che l'installer di Claude Code si blocca quando WORKDIR è di proprietà di root. Poi SQLite si blocca sul mount NAS. E poi—
HolyClaude è il container che ho costruito dopo aver risolto ognuno di questi problemi.
Lo uso ogni giorno sul mio server da settimane. Ogni bug è stato individuato, diagnosticato e corretto. Ogni caso limite è stato gestito. Ogni "perché non funziona in Docker" ha trovato risposta.
Lo scarichi. Lo avvii. Apri il browser. Costruisci.
💳 Usa il tuo abbonamento esistente
Questo esegue la vera Claude Code CLI. Non un wrapper. Non un proxy. Non un imitatore.
Il tuo account Anthropic esistente funziona direttamente:
- Piano Claude Max/Pro — autenticati tramite l'interfaccia web (OAuth), esattamente come con Claude Code desktop
- Chiave API Anthropic — impostala tramite l'interfaccia web, stessa fatturazione di sempre
- Nessun costo aggiuntivo — HolyClaude è gratuito e open source. Paghi solo Anthropic per quello che usi, come già fai.
HolyClaude non tocca le tue credenziali. Sono conservate localmente nel tuo volume bind-mounted (
./data/claude/), esattamente come sarebbe su bare metal.
Indice dei contenuti
⚡ Avvio rapido
1. Crea una cartella per HolyClaude:
mkdir holyclaude && cd holyclaude
2. Crea un file docker-compose.yaml. Copia uno dei template qui sotto:
- Template rapido — minimale, zero configurazione, funziona subito
- Template completo — tutte le opzioni, completamente documentato
3. Scarica e avvia:
docker compose up -d
4. Apri l'interfaccia web:
http://localhost:3001
5. Crea un account CloudCLI (ci vogliono 10 secondi), accedi con il tuo account Anthropic e sei operativo.
Nessun file
.env. Nessuna pre-configurazione. Nessun bisogno di leggere 40 pagine di documentazione prima di iniziare. Funziona e basta.
💻 Piattaforme supportate
| Piattaforma | Stato | Note |
|---|---|---|
| Linux (amd64) | ✅ Completamente supportato | Prestazioni native, consigliato |
| Linux (arm64) | ✅ Completamente supportato | Raspberry Pi 4+, Oracle Cloud, AWS Graviton |
| macOS (Docker Desktop) | ✅ Completamente supportato | Apple Silicon e Intel tramite Docker Desktop |
| Windows (WSL2 + Docker Desktop) | ✅ Completamente supportato | Richiede backend WSL2 |
| Synology / QNAP NAS | ✅ Completamente supportato | Usa CHOKIDAR_USEPOLLING=true per mount SMB |
| Kubernetes | 🔜 Prossimamente | Helm chart in programma |
🌟 Perché HolyClaude
L'ho costruito perché ero stanco di ripetere la stessa configurazione ogni volta. Installare Claude Code, collegare un'interfaccia web, configurare Chromium in Docker, risolvere problemi di permessi, fare debug della supervisione dei processi. Ogni. Volta.
Così ho creato un container che fa tutto. E poi ho incontrato ogni possibile bug al posto tuo.
| HolyClaude | Farlo da soli | |
|---|---|---|
| Configurazione | 30 secondi | 1-2 ore (se va bene) |
| Claude Code | Pre-installato, pre-configurato, pronto | Installa, configura, fai debug del blocco dell'installer, correggi WORKDIR |
| Interfaccia web | CloudCLI incluso con plugin | Trova un'interfaccia web, installala, configurala, collegala a Claude |
| Browser headless | Chromium + Xvfb + Playwright, configurati | Installa Chromium, installa Xvfb, configura il display :99, correggi shm, sandbox, seccomp... |
| CLI AI | 7 provider, un container | Installa ognuna separatamente su 3 package manager |
| Strumenti di sviluppo | 50+ strumenti, pronti | apt-get install / npm i -g / pip install per la prossima ora |
| Gestione dei processi | s6-overlay (riavvio automatico, shutdown controllato) | Scrivi la tua configurazione supervisord o spera che il restart di Docker funzioni |
| Persistenza | Bind mount, le credenziali sopravvivono a tutto | Capire i volumi Docker, fare debug di "perché questa è una directory e non un file" |
| Aggiornamenti | docker pull && docker compose up -d |
Aggiorna 50 strumenti manualmente, prega che non si rompa nulla |
| Multi-arch | AMD64 + ARM64 | Prega che il tuo Dockerfile compili su ARM |
L'ultima riga di ogni configurazione manuale è "funziona sulla mia macchina." HolyClaude funziona su ogni macchina.
💳 Abbonamento e autenticazione
HolyClaude esegue la Claude Code CLI ufficiale di Anthropic. Il tuo account esistente funziona immediatamente.
Cosa funziona:
| Metodo di autenticazione | Come | Costo |
|---|---|---|
| Piano Claude Max/Pro (abbonamento) | Accedi tramite l'interfaccia web CloudCLI — stesso flusso OAuth del desktop | Il tuo abbonamento esistente, nessun costo aggiuntivo |
| Chiave API Anthropic | Incolla la tua chiave API nell'interfaccia web | Pay-per-use, stessa fatturazione Anthropic |
Cosa non funziona:
| Perché | |
|---|---|
| Chiave API OpenAI per Claude | Aziende diverse, API diverse. Le chiavi OpenAI funzionano con la Codex CLI (anch'essa pre-installata) |
Abbonati ChatGPT Plus/Pro: Il tuo abbonamento funziona con la Codex CLI. Esegui
codex login --device-authall'interno del container per autenticarti con il tuo account ChatGPT.
Altre CLI AI incluse:
| CLI | Cosa ti serve |
|---|---|
| Gemini CLI | Chiave API Google AI (GEMINI_API_KEY) |
| OpenAI Codex | Chiave API OpenAI (OPENAI_API_KEY) o abbonamento ChatGPT Plus/Pro (codex login --device-auth) |
| Cursor | Chiave API Cursor (CURSOR_API_KEY) |
| TaskMaster AI | Usa le tue chiavi AI provider (Anthropic, OpenAI, ecc.) |
| Junie | Account JetBrains (abbonamento JetBrains AI) |
| OpenCode | Configura tramite TUI opencode (supporta più provider) |
HolyClaude è gratuito e open source. Paghi solo i tuoi provider AI per l'utilizzo, come già fai. Non intercettiamo, non facciamo proxy e non tocchiamo le tue credenziali. Vivono nel tuo bind mount locale.
📦 Varianti dell'immagine
Due versioni. Stessa qualità. Scegli il tuo peso.
| Tag | Cosa ottieni | Ideale per |
|---|---|---|
latest |
Tutto pre-installato — ogni strumento, ogni libreria, ogni CLI | La maggior parte degli utenti. Zero tempo di attesa. Claude non deve mai fermarsi per installare qualcosa. |
slim |
Solo gli strumenti di base — Claude installa gli extra su richiesta | VPS piccoli, disco limitato, banda a consumo |
X.Y.Z |
Immagine completa, versione fissa | Stabilità in produzione — controlli tu quando aggiornare |
X.Y.Z-slim |
Immagine slim, versione fissa | Produzione + footprint ridotto |
# Completa — batterie incluse (consigliata)
docker pull coderluii/holyclaude
# Slim — leggera ed efficiente
docker pull coderluii/holyclaude:slim
latestè sempre l'immagine completa. Utenti slim: non preoccupatevi — quando chiedete a Claude di fare qualcosa che richiede uno strumento mancante, lo installa in pochi secondi. Ottieni le stesse funzionalità, solo con un download iniziale più piccolo.
🐳 Docker Compose — Rapido
Il template "voglio solo che funzioni". Copia questo intero blocco in un file docker-compose.yaml:
# ==============================================================================
# HolyClaude — Quick Start
# Just run: docker compose up -d
# Then open: http://localhost:3001
# ==============================================================================
services:
holyclaude:
image: coderluii/holyclaude:latest # Full image (use :slim for smaller download)
container_name: holyclaude
hostname: holyclaude
restart: unless-stopped
shm_size: 2g # Chromium needs this — don't remove
network_mode: bridge
cap_add:
- SYS_ADMIN # Required: Chromium sandboxing
- SYS_PTRACE # Required: debugging tools
security_opt:
- seccomp=unconfined # Required: Chromium in Docker
ports:
- "3001:3001" # CloudCLI web UI
volumes:
#
# ./data/claude — Your settings, credentials, API keys, and Claude's memory.
# This is what survives container rebuilds.
# NEVER delete this folder — your auth lives here.
#
- ./data/claude:/home/claude/.claude
#
# ./workspace — Your code. All projects go here.
# Bind-mounted so you can access files from your host.
#
- ./workspace:/workspace
environment:
- TZ=UTC # Your timezone (e.g., America/New_York, Europe/London)
Poi:
docker compose up -d
Apri http://localhost:3001. Crea un account CloudCLI. Accedi con il tuo account Anthropic. Costruisci qualcosa.
Questa è tutta la configurazione. Hai finito.
Perché
SYS_ADMIN+seccomp=unconfined? Chromium ha bisogno di questi permessi per funzionare dentro Docker — è lo standard per qualsiasi browser containerizzato (documentazione Playwright, Puppeteer, ogni pipeline CI che esegue test nel browser). Senza di essi, Chromium va in crash all'avvio. Non è un rischio per la sicurezza specifico di HolyClaude.
Perché
shm_size: 2g? Docker assegna ai container 64MB di memoria condivisa per impostazione predefinita. Chromium usa/dev/shmintensivamente per il rendering delle schede. A 64MB, le schede vanno in crash casualmente. 2GB è il minimo consigliato per qualsiasi configurazione Chromium-in-Docker.
🐋 Docker Compose — Completo
Stessa immagine, ogni opzione esposta. Copia questo intero blocco in un file docker-compose.yaml:
# ==============================================================================
# HolyClaude — Full Configuration
# All options documented inline.
# Detailed docs: https://github.com/CoderLuii/HolyClaude/blob/main/docs/configuration.md
# ==============================================================================
services:
holyclaude:
image: coderluii/holyclaude:latest # Full image (use :slim for smaller download)
container_name: holyclaude
hostname: holyclaude
restart: unless-stopped
shm_size: 2g # Chromium shared memory — increase to 4g for heavy browser use
network_mode: bridge
cap_add:
- SYS_ADMIN # Required: Chromium sandboxing
- SYS_PTRACE # Required: debugging tools (strace, lsof)
security_opt:
- seccomp=unconfined # Required: Chromium syscall requirements
ports:
#
# CloudCLI web UI — this is the only port you need.
# Override the host-side port from `.env` if 3001 is already in use.
#
- "${HOLYCLAUDE_HOST_PORT:-3001}:3001"
#
# Dev server ports — uncomment as needed.
# These let you access dev servers running inside the container from your host browser.
#
# - "3000:3000" # Next.js / Express
# - "4321:4321" # Astro
# - "5173:5173" # Vite
# - "8787:8787" # Wrangler (Cloudflare Workers)
# - "9229:9229" # Node.js debugger
volumes:
#
# PERSISTENT DATA
#
# ./data/claude — Settings, credentials, API keys, Claude's memory file.
# Survives container rebuilds. NEVER delete this folder.
# Override the host path from `.env` if you want it elsewhere.
#
- ${HOLYCLAUDE_HOST_CLAUDE_DIR:-./data/claude}:/home/claude/.claude
#
# ./workspace — Your code and projects. Everything you build goes here.
# Accessible from your host machine.
# Override the host path from `.env` if you want a different root.
#
- ${HOLYCLAUDE_HOST_WORKSPACE_DIR:-./workspace}:/workspace
environment:
#
# TIMEZONE
# Full list: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
#
- TZ=UTC
#
# PERFORMANCE
# Node.js heap memory limit in MB. Increase if you work on large monorepos
# and hit out-of-memory errors. 4096 (4GB) is a solid default.
#
- NODE_OPTIONS=--max-old-space-size=4096
#
# USER MAPPING
# Match these to your host user so files created inside the container
# have the right ownership on your host. Run `id -u` and `id -g` on your host.
#
- PUID=1000
- PGID=1000
#
# SMB/CIFS NETWORK MOUNTS
# Only enable these if your volumes are on a NAS, Samba share, or CIFS mount.
# They enable polling-based file watching since network mounts don't support inotify.
# Leave commented out for local storage — polling uses more CPU.
#
# - CHOKIDAR_USEPOLLING=1
# - WATCHFILES_FORCE_POLLING=true
#
# NOTIFICATIONS (optional)
# Get notified when Claude finishes a task or hits an error.
# Uses Apprise — supports 100+ services. Also requires creating a flag file
# inside the container: touch ~/.claude/notify-on
#
# - NOTIFY_DISCORD=discord://webhook_id/webhook_token
# - NOTIFY_TELEGRAM=tg://bot_token/chat_id
# - NOTIFY_PUSHOVER=pover://user_key@app_token
# - NOTIFY_SLACK=slack://token_a/token_b/token_c
# - NOTIFY_EMAIL=mailto://user:pass@gmail.com?to=you@gmail.com
# - NOTIFY_GOTIFY=gotify://hostname/token
# - NOTIFY_URLS= # catch-all: comma-separated Apprise URLs
#
# AI PROVIDER KEYS (optional)
# Claude Code can authenticate via web UI (OAuth) or ANTHROPIC_API_KEY.
# Set these if you want to use additional AI CLIs or API-based auth.
#
# - GEMINI_API_KEY=your_key
# - OPENAI_API_KEY=your_key
# - CURSOR_API_KEY=your_key
Poi:
docker compose up -d
Se vuoi cambiare la porta lato host o i percorsi bind-mount senza modificare il compose, copia .env.example in .env e imposta:
HOLYCLAUDE_HOST_PORT=3003
HOLYCLAUDE_HOST_CLAUDE_DIR=./data/claude
HOLYCLAUDE_HOST_WORKSPACE_DIR=./workspace
Questi valori vengono letti da Docker Compose sull'host. Non sono variabili d'ambiente del container.
Cosa controlla ogni sezione:
| Sezione | Cosa fa | Quando cambiarla |
|---|---|---|
| Timezone | Orologio del container | Sempre — imposta il tuo fuso orario locale |
| Performance | Limite di memoria Node.js | Solo se incorri in errori OOM su progetti grandi |
| User mapping | Permessi dei file tra container e host | Se ricevi errori "permission denied" (id -u e id -g sul tuo host) |
| SMB/CIFS | Modalità polling del file watcher | Solo se i tuoi volumi si trovano su NAS o condivisione di rete |
| Notifications | Avvisi push tramite Apprise (Discord, Telegram, Slack, Email, 100+ servizi) | Se vuoi allontanarti e sapere quando Claude ha finito |
| AI providers | Chiavi API per Gemini, Codex, Cursor, Junie, OpenCode | Se vuoi usare CLI AI diverse da Claude |
Ogni singola variabile d'ambiente è opzionale. Il container funziona perfettamente con solo
TZ=UTC. Tutto il resto ha valori predefiniti ragionevoli o viene gestito tramite l'interfaccia web.
🔧 Variabili d'ambiente
Il riferimento completo. Ogni variabile, il suo valore predefinito, cosa fa.
| Variabile | Predefinito | Cosa fa |
|---|---|---|
TZ |
UTC |
Fuso orario del container |
PUID |
1000 |
ID utente del container — abbina al tuo host per evitare problemi di permessi |
PGID |
1000 |
ID gruppo del container — abbina al tuo host per evitare problemi di permessi |
NODE_OPTIONS |
--max-old-space-size=4096 |
Limite memoria heap Node.js in MB |
GIT_USER_NAME |
HolyClaude User |
Autore dei commit Git (impostato una volta al primo avvio) |
GIT_USER_EMAIL |
noreply@holyclaude.local |
Email dei commit Git (impostata una volta al primo avvio) |
CHOKIDAR_USEPOLLING |
(non impostato) | Imposta a 1 per SMB/CIFS — abilita i file watcher in polling |
WATCHFILES_FORCE_POLLING |
(non impostato) | Imposta a true per SMB/CIFS — abilita il polling Python |
NOTIFY_DISCORD |
(non impostato) | URL webhook Discord per le notifiche |
NOTIFY_TELEGRAM |
(non impostato) | URL bot Telegram per le notifiche |
NOTIFY_PUSHOVER |
(non impostato) | URL Pushover per le notifiche |
NOTIFY_SLACK |
(non impostato) | URL webhook Slack per le notifiche |
NOTIFY_EMAIL |
(non impostato) | URL email (SMTP) per le notifiche |
NOTIFY_GOTIFY |
(non impostato) | URL Gotify per le notifiche |
NOTIFY_URLS |
(non impostato) | Catch-all — URL Apprise separati da virgola |
ANTHROPIC_API_KEY |
(non impostato) | Chiave API Anthropic (alternativa all'OAuth dell'interfaccia web) |
ANTHROPIC_AUTH_TOKEN |
(non impostato) | Token di autenticazione Anthropic (alternativa alla chiave API) |
ANTHROPIC_BASE_URL |
(non impostato) | Endpoint API Anthropic personalizzato (proxy, deployment privati) |
CLAUDE_CODE_USE_BEDROCK |
(non impostato) | Imposta a 1 per usare il backend Amazon Bedrock |
CLAUDE_CODE_USE_VERTEX |
(non impostato) | Imposta a 1 per usare il backend Google Vertex AI |
GEMINI_API_KEY |
(non impostato) | Chiave API Google Gemini |
OPENAI_API_KEY |
(non impostato) | Chiave API OpenAI (per Codex CLI, oppure usa codex login --device-auth per abbonamento ChatGPT) |
CURSOR_API_KEY |
(non impostato) | Chiave API Cursor |
OLLAMA_HOST |
(non impostato) | URL endpoint Ollama (es. http://host.docker.internal:11434) |
🚀 Cosa c'è dentro
Questo non è un container minimale. Questa è un'intera workstation di sviluppo.
Entrambe le varianti (full + slim)
Node.js 22 LTS + pacchetti npm globali
| Pacchetto | A cosa serve |
|---|---|
typescript, tsx |
Compilazione ed esecuzione TypeScript |
pnpm |
Package manager veloce e con poco utilizzo disco |
vite, esbuild |
Strumenti di build ultra-rapidi |
eslint, prettier |
Qualità del codice e formattazione |
serve, nodemon |
Server di file statici, server di sviluppo con riavvio automatico |
concurrently |
Esegui più script in parallelo |
dotenv-cli |
Carica variabili d'ambiente da file .env |
Pacchetti Python 3
| Pacchetto | A cosa serve |
|---|---|
requests, httpx |
Client HTTP |
beautifulsoup4, lxml |
Web scraping e parsing HTML |
Pillow |
Elaborazione immagini (pre-compilato — nessuna attesa) |
pandas, numpy |
Manipolazione dati (pre-compilati — davvero, non vuoi fare pip install di questi a runtime) |
openpyxl |
Lettura/scrittura file Excel |
python-docx |
Lettura/scrittura documenti Word |
jinja2, markdown |
Templating e rendering markdown |
pyyaml, python-dotenv |
Parsing file di configurazione |
rich, click, tqdm |
CLI eleganti e barre di avanzamento |
playwright |
Automazione browser (Chromium già configurato e pronto) |
Strumenti di sistema
| Strumento | A cosa serve |
|---|---|
git, gh |
Controllo versione + GitHub CLI (PR, issue, release dal terminale) |
ripgrep (rg), fd, fzf |
Ricerca ultra-veloce — Claude li usa continuamente |
bat, tree, jq |
Cat migliore (syntax highlighting), alberi di directory, elaborazione JSON |
curl, wget |
Download HTTP |
tmux |
Terminal multiplexer — esegui cose in background |
htop, lsof, strace |
Monitoraggio processi e debug |
imagemagick |
Conversione immagini (convert, identify, mogrify) |
chromium |
Browser headless — screenshot, Playwright, Lighthouse |
psql, redis-cli, sqlite3 |
Interfaccia diretta con database |
openssh-client |
SSH verso altri sistemi |
CLI AI — ogni provider principale
| CLI | Comando | A cosa serve |
|---|---|---|
| Claude Code | claude |
Il protagonista principale — ci stai girando dentro |
| Gemini CLI | gemini |
Agente di coding AI di Google |
| OpenAI Codex | codex |
Agente di coding di OpenAI |
| Cursor | cursor |
Agente AI di Cursor |
| TaskMaster AI | task-master |
Pianificazione e orchestrazione dei task |
| Junie | junie |
Agente di coding AI di JetBrains |
| OpenCode | opencode |
Agente AI open source (più provider) |
Sette CLI AI. Un container. Passa da una all'altra istantaneamente. Nessun'altra immagine Docker fa questo.
Solo immagine full (pacchetti aggiuntivi)
L'immagine full include tutto quanto sopra, più:
Pacchetti npm aggiuntivi — deployment, ORM, performance
| Pacchetto | A cosa serve |
|---|---|
wrangler, @cloudflare/next-on-pages |
Deployment Cloudflare Workers |
vercel |
Deployment Vercel |
netlify-cli |
Deployment Netlify |
az |
Azure CLI per deployment e gestione cloud |
prisma, drizzle-kit |
I due ORM Node.js più popolari |
pm2 |
Process manager per produzione |
eas-cli |
Build Expo / React Native |
lighthouse, @lhci/cli |
Audit delle performance (Chromium è già disponibile) |
sharp-cli |
CLI per elaborazione immagini |
json-server, http-server |
Mock REST API, server di file statici |
@marp-team/marp-cli |
Da Markdown a presentazioni |
Pacchetti Python aggiuntivi — PDF, visualizzazione dati, framework web
| Pacchetto | A cosa serve |
|---|---|
reportlab, weasyprint, cairosvg, fpdf2, PyMuPDF, pdfkit, img2pdf |
Ogni libreria PDF principale. Generali, leggili, convertili, uniscili. |
xlsxwriter, xlrd |
Formati Excel oltre a quanto copre openpyxl |
matplotlib, seaborn |
Visualizzazione dati e grafici |
python-pptx |
Generazione PowerPoint |
fastapi, uvicorn |
Framework web Python |
httpie |
Client HTTP user-friendly (come curl ma leggibile) |
Pacchetti di sistema aggiuntivi — media, documenti
| Pacchetto | A cosa serve |
|---|---|
pandoc |
Converti tra qualsiasi formato di documento (markdown, HTML, PDF, docx, epub...) |
ffmpeg |
Elaborazione video e audio (estrai, converti, trascrivi) |
libvips-dev |
Libreria di elaborazione immagini ad alte prestazioni |
Utenti slim: Manca un pacchetto? Chiedi a Claude. Installa pacchetti npm/pip in pochi secondi. I pacchetti di sistema (pandoc, ffmpeg) richiedono 1-2 minuti. Ottieni le stesse funzionalità — l'immagine full ha semplicemente zero tempo di attesa.
🤖 Provider CLI AI
Sette CLI AI. Un container. Nessun'altra immagine Docker ti offre questo.
| Provider | Comando | Come autenticarsi | Abbonamento supportato? |
|---|---|---|---|
| Claude Code | claude |
Interfaccia web CloudCLI (OAuth) | Sì — piano Max/Pro o chiave API |
| Gemini CLI | gemini |
Variabile d'ambiente GEMINI_API_KEY |
Chiave API (pay-per-use) |
| OpenAI Codex | codex |
OPENAI_API_KEY oppure codex login --device-auth |
Sì — ChatGPT Plus/Pro/Team/Enterprise o chiave API |
| Cursor | cursor |
Variabile d'ambiente CURSOR_API_KEY |
Chiave API |
| TaskMaster AI | task-master |
Usa le chiavi AI provider esistenti | Funziona con le chiavi configurate |
| Junie | junie |
Abbonamento JetBrains AI | Account JetBrains richiesto |
| OpenCode | opencode |
Configura tramite TUI | Supporta più provider |
Claude Code è la CLI principale. Le altre sono disponibili perché a volte vuoi un secondo parere, o i punti di forza di un modello specifico, o stai confrontando output. Averle tutte a portata di
Tabè il punto centrale.
🦙 Usare Ollama
HolyClaude funziona con Ollama come alternativa a un abbonamento Anthropic. Imposta due variabili d'ambiente e usa modelli locali o cloud.
Consulta la guida completa: docs/ollama.md
🏗️ Architettura
graph TB
subgraph Docker Container
EP["entrypoint.sh"] --> BS["bootstrap.sh\n(first boot only)"]
EP --> S6["s6-overlay\n(PID 1)"]
S6 --> CC["CloudCLI\n(:3001)"]
S6 --> XV["Xvfb\n(:99)"]
CC --> CLAUDE["Claude Code CLI"]
CLAUDE --> TOOLS["Dev Tools\n(Node, Python, Git...)"]
CLAUDE --> CHROME["Chromium\n(headless)"]
XV -.-> CHROME
end
subgraph Host
DATA["./data/claude"] -.->|bind mount| HOME["~/.claude"]
WS["./workspace"] -.->|bind mount| WORK["/workspace"]
end
USER["Browser"] -->|":3001"| CC
style S6 fill:#2d3748,color:#fff
style CC fill:#6366f1,color:#fff
style CLAUDE fill:#f59e0b,color:#000
Come si incastrano i pezzi
-
Il container si avvia —
entrypoint.shviene eseguito come root. Rimappa UID/GID per corrispondere al tuo utente host, pre-crea i file necessari (prevenendo il bug di Docker che li "crea come directory"), verifica se è il primo avvio. -
Solo al primo avvio —
bootstrap.shviene eseguito una volta. Copia le impostazioni predefinite, il template di memoria, configura l'identità git. Crea un file sentinella (.holyclaude-bootstrapped) così non viene mai eseguito di nuovo. Le tue personalizzazioni sono al sicuro da quel momento in poi. -
s6-overlay prende il controllo come PID 1 — Non è supervisord. È s6-overlay, progettato appositamente per Docker. Supervisiona CloudCLI e Xvfb. Riavvia automaticamente in caso di crash. Gestisce i segnali. Riepiloga i processi zombi. Si spegne in modo controllato.
-
CloudCLI serve l'interfaccia web — Porta 3001. Interfaccia basata su browser per Claude Code con gestione progetti, sessioni multiple e plugin (statistiche progetto + terminale web inclusi).
-
Xvfb fornisce un display virtuale — Chromium ha bisogno di uno schermo su cui renderizzare, anche in modalità "headless". Xvfb gli fornisce un display virtuale 1920x1080 su
:99. Ecco perché Playwright, gli screenshot e Lighthouse funzionano tutti immediatamente.
Consulta docs/architecture.md per l'approfondimento tecnico completo — incluso perché abbiamo scelto s6 al posto di supervisord, perché i plugin sono integrati nell'immagine e perché runuser invece di su.
📁 Struttura del progetto
holyclaude/
├── .github/ # Workflow CI/CD, template issue e PR
│ ├── FUNDING.yml # Link sponsor/donazioni
│ ├── ISSUE_TEMPLATE/ # Bug report, feature request, package request
│ ├── pull_request_template.md
│ ├── SECURITY.md # Policy di sicurezza
│ └── workflows/ # Automazione build e push Docker
├── assets/ # Immagini logo e banner
├── config/ # Configurazione Claude Code
│ ├── claude-memory-full.md
│ ├── claude-memory-slim.md
│ └── settings.json
├── docs/ # Documentazione estesa
│ ├── architecture.md
│ ├── CHANGELOG.md
│ ├── configuration.md
│ ├── dockerhub-description.md
│ ├── ollama.md
│ └── troubleshooting.md
├── scripts/ # Script del ciclo di vita del container
│ ├── bootstrap.sh # Configurazione al primo avvio
│ ├── entrypoint.sh # Entrypoint del container
│ └── notify.py # Helper notifiche (Apprise)
├── s6-overlay/ # Supervisione processi (servizi s6-rc)
├── Dockerfile # Build single-stage
├── docker-compose.yaml # Avvio rapido (configurazione minimale)
├── docker-compose.full.yaml # Configurazione completa (tutte le opzioni)
├── LICENSE
└── README.md
💾 Dati e persistenza
| Cosa | Dove (container) | Dove (host) | Sopravvive al rebuild? |
|---|---|---|---|
| Impostazioni, credenziali, chiavi API | /home/claude/.claude |
./data/claude |
Sì |
| Il tuo codice e progetti | /workspace |
./workspace |
Sì |
| Account CloudCLI | /home/claude/.cloudcli |
(solo container) | No |
| Stato onboarding | /home/claude/.claude.json |
(solo container) | No |
Cosa sopravvive a docker compose down && docker compose up:
- La tua autenticazione Anthropic e le chiavi API
- Impostazioni Claude Code e memoria (
CLAUDE.md) - Tutto il tuo codice in
./workspace - Configurazione Git
Cosa dovrai rifare (10 secondi):
- Account web CloudCLI — registrazione rapida, tutto qui
Riattivare la configurazione del primo avvio:
# Elimina il file sentinella — NON l'intera cartella
rm ./data/claude/.holyclaude-bootstrapped
docker compose restart holyclaude
Non eliminare mai
./data/claude/per intero. Lì vivono le tue credenziali. Elimina il file sentinella se vuoi un bootstrap pulito. Elimina file di configurazione specifici se vuoi ripristinare le impostazioni. Ma non cancellare mai l'intera cartella.
🔒 Permessi
Claude Code viene eseguito in modalità allowEdits per impostazione predefinita. Questa è l'impostazione più sicura e utile:
| Azione | Consentita? |
|---|---|
| Leggere file | Sì |
| Modificare / creare file | Sì |
| Eseguire comandi shell | Ti chiede prima |
| Installare pacchetti | Ti chiede prima |
Vuoi il bypass completo? (utenti avanzati)
È come lo uso personalmente. Modifica ./data/claude/settings.json sul tuo host:
{
"permissions": {
"defaultMode": "bypassPermissions"
}
}
La modalità bypass significa che Claude esegue qualsiasi comando senza conferma. Veloce, potente, ed esattamente quello che vuoi se ti fidi di ciò che stai costruendo. Ma
allowEditsè il valore predefinito sicuro per una ragione.
🔔 Notifiche
Allontanati dal computer e sappi quando Claude ha finito. Usa Apprise per le notifiche — supporta 100+ servizi tra cui Discord, Telegram, Slack, Email, Pushover, Gotify e molti altri.
Per abilitare:
- Aggiungi una o più variabili
NOTIFY_*all'environmentdel tuo compose:- NOTIFY_DISCORD=discord://webhook_id/webhook_token - NOTIFY_TELEGRAM=tg://bot_token/chat_id - All'interno del container:
touch ~/.claude/notify-on
Consulta la documentazione di configurazione per tutte le variabili supportate e i formati URL.
Per disabilitare: rm ~/.claude/notify-on
Eventi che attivano le notifiche:
| Evento | Cosa è successo |
|---|---|
stop |
Claude ha completato il task corrente |
error |
Si è verificato un errore nell'uso di uno strumento |
Completamente silenzioso quando non configurato. Nessuna variabile
NOTIFY_*impostata? Nessun file flag? Zero chiamate di rete. Zero spam nei log. Zero overhead.
🔄 Aggiornamento
# Scarica l'immagine più recente
docker compose pull
# Ricrea il container con la nuova immagine
docker compose up -d
I tuoi dati persistono in ./data/claude e ./workspace — l'aggiornamento sostituisce solo il container, non i tuoi file.
Per fissare una versione specifica invece di latest:
image: coderluii/holyclaude:1.1.2 # instead of :latest
🚧 Risoluzione dei problemi
CloudCLI mostra la directory predefinita sbagliata
CloudCLI si apre su /home/claude invece di /workspace.
Causa: WORKSPACES_ROOT non raggiunge il processo CloudCLI. Le variabili d'ambiente di docker-compose non passano attraverso s6-setuidgid di s6-overlay — viene eseguito con un ambiente pulito per design (funzionalità di sicurezza, non un bug).
Soluzione: Già gestita in HolyClaude. Lo script di esecuzione s6 imposta WORKSPACES_ROOT=/workspace direttamente nell'ambiente del processo.
SQLite "database is locked"
Causa: Database SQLite su mount di rete SMB/CIFS. CIFS non supporta il locking a livello di file richiesto da SQLite.
Soluzione: Non conservare database SQLite su condivisioni di rete. HolyClaude mantiene .cloudcli nello storage locale del container esattamente per questo motivo. Se hai database SQLite personali in /workspace su un NAS, spostali in un percorso locale.
Chromium va in crash / pagine bianche / errori di tab
Causa: Memoria condivisa insufficiente. Docker imposta un limite predefinito di 64MB.
Soluzione: Assicurati di avere shm_size: 2g nel tuo file compose. Per uso intensivo del browser (molte tab, pagine complesse), aumenta a 4g.
I file watcher non rilevano i cambiamenti (hot reload non funziona)
Causa: I mount di rete SMB/CIFS non supportano inotify.
Soluzione: Abilita il polling nell'ambiente del tuo compose:
- CHOKIDAR_USEPOLLING=1
- WATCHFILES_FORCE_POLLING=true
Nota: Il polling usa più CPU di inotify. Abilitalo solo su mount di rete.
Errori "permission denied"
Causa: UID/GID del container non corrisponde alla proprietà dei file sull'host.
Soluzione:
# Sul tuo host
id -u # → questo è il tuo PUID
id -g # → questo è il tuo PGID
Impostali nel tuo file compose:
- PUID=1000
- PGID=1000
Docker crea .claude.json come directory
Causa: Se un file di destinazione di un bind-mount non esiste prima dell'avvio del container, Docker lo crea generosamente come directory. Grazie, Docker.
Soluzione: Già gestita — entrypoint.sh lo pre-crea come file.
Consulta docs/troubleshooting.md per la guida completa, incluse tutte le problematiche SMB/CIFS e la storia completa dei bug incontrati e risolti.
⚠️ Problemi noti
Questi non sono bug di HolyClaude — sono problemi upstream o compromessi intenzionali.
| Problema | Perché | Soluzione alternativa |
|---|---|---|
| Pulsante "Continue in Shell" non funziona | Bug upstream di CloudCLI (race condition nell'inizializzazione del terminale) | Usa invece il plugin Web Terminal (pre-installato) |
| Cursor CLI "Command timeout" | Nessuna chiave API configurata — solo estetico, non influisce su nulla | Imposta CURSOR_API_KEY o ignoralo |
| Account CloudCLI perso al rebuild | SQLite non può persistere su mount di rete — compromesso intenzionale | Ricrea l'account (~10 secondi) |
| Notifiche push web "not supported" | Limitazione del browser in CloudCLI, comportamento standard | Usa invece le notifiche Apprise (vedi Notifiche) |
🛠️ Build locale
Vuoi costruire l'immagine tu stesso invece di scaricarla da Docker Hub? Vai pure:
git clone https://github.com/CoderLuii/HolyClaude.git
cd holyclaude
# Build immagine full
docker build -t holyclaude .
# Build immagine slim
docker build --build-arg VARIANT=slim -t holyclaude:slim .
# Build per ARM (Apple Silicon, Raspberry Pi, AWS Graviton)
docker buildx build --platform linux/arm64 -t holyclaude .
Poi usa image: holyclaude invece di image: coderluii/holyclaude:latest nel tuo file compose.
📊 Alternative
Come si confronta HolyClaude con altri approcci?
| Approccio | Interfaccia web | Multi-AI | Strumenti pre-configurati | Browser headless | Configurazione con un comando | Persistenza |
|---|---|---|---|---|---|---|
| HolyClaude | CloudCLI | 5 CLI | 50+ strumenti | Chromium + Xvfb + Playwright | docker compose up |
Bind mount |
| Claude Code (bare metal) | No | No | Installa tu stesso | Installa tu stesso | Installazione multi-step | Manuale |
| Claude Code + oh-my-openagent | No | Sì (multi-modello) | Alcuni | No | npm install | Manuale |
| DIY Docker + Claude Code | Forse | Forse | Quello che aggiungi | Se lo configuri | Se scrivi il Dockerfile | Se imposti i volumi |
| Cursor IDE | Integrata | Solo Cursor | Inclusi nell'IDE | No | Scarica l'app | Dati dell'app |
HolyClaude non compete con gli agenti di coding — è il layer infrastrutturale che li fa funzionare meglio a tutti. È il container in cui li esegui.
🚀 Roadmap
Cosa verrà dopo:
| Stato | Funzionalità |
|---|---|
| 🔜 | Build native ARM — immagini ARM64 native ottimizzate, non solo emulate |
| 🔜 | Integrazione tunnel VS Code — VS Code Server integrato o tunnel per la connessione da VS Code desktop |
| 🔜 | Routing delle notifiche — destinazioni di notifica diverse per tipo di evento (errori su Telegram, completamenti su Discord) |
Hai un'idea? Avvia una discussione o richiedi una funzionalità.
🏆 Costruito con HolyClaude
Stai usando HolyClaude per costruire qualcosa? Ci piacerebbe vederlo.
Apri una issue con il label showcase o invia una PR per aggiungere il tuo progetto qui:
Sii il primo ad aggiungere il tuo progetto qui.
🤝 Contribuire
I contributi sono benvenuti. Questo progetto è nato dall'uso quotidiano reale e migliora quando più persone lo usano e trovano casi limite.
- Fai un fork
- Crea un branch (
git checkout -b feature/qualcosa) - Fai il commit
- Fai il push
- Apri una PR
Bug, richieste di funzionalità, domande: apri una issue.
Contatti
| Canale | Per |
|---|---|
| GitHub Discussions | Domande, mostra la tua configurazione, idee |
| Issues | Segnalazioni bug, richieste di funzionalità e pacchetti |
| Security Advisories | Segnalazioni di vulnerabilità (private) |
Vuoi aggiungere uno strumento?
Usa il template di issue 📦 Package Request. Includi il nome del pacchetto, il metodo di installazione e quale variante (full/slim) dovrebbe essere il target.
❤️ Supporto
HolyClaude è gratuito, open source e mantenuto da un singolo sviluppatore che lo usa ogni giorno.
Se ti ha fatto risparmiare tempo, ecco come puoi aiutare:
- Metti una stella a questo repo — è la singola cosa più importante che puoi fare per la visibilità
- Condividilo — dillo a un amico, postalo, twittalo
- Apri issue — segnalazioni di bug e richieste di funzionalità rendono HolyClaude migliore per tutti
- Contribuisci — le PR sono sempre benvenute
📜 Software di terze parti
L'immagine Docker di HolyClaude include software di terze parti, ognuno con la propria licenza. Componenti principali:
| Componente | Licenza | Sorgente |
|---|---|---|
| CloudCLI | GPL-3.0 | siteboon/claudecodeui |
| s6-overlay | ISC | just-containers/s6-overlay |
| Node.js | MIT | nodejs/node |
Consulta THIRD-PARTY-NOTICES per tutti i dettagli, inclusi gli avvisi di modifica. Il codice sorgente di HolyClaude è distribuito con licenza MIT.
📄 Licenza
MIT — vedi LICENSE. Usalo come vuoi.
Costruito da CoderLuii · coderluii.dev
Questo container è quello che uso ogni giorno. Se ti fa risparmiare anche solo metà del tempo di configurazione che ha fatto risparmiare a me, una stella sarebbe gradita.