> ## Content Index > Fetch the complete content index at: https://adrianoamalfi.com/llms.txt > Use this file to discover other available public pages before exploring further. # Multica: installare e usare la piattaforma open-source per managed agents - URL: https://adrianoamalfi.com/tech-scratchpad/multica-guida-installazione-self-hosting/ - Published: 2026-07-29T20:13:28.000Z - Updated: 2026-07-29T20:29:03.000Z - Description: Guida passo-passo per installare Multica in self-hosting, connettere agent CLI e assegnare il primo task. - Author: Adriano Amalfi - Tags: Scratchpad, AI Agentica, Tutorial, Claude Code, Docker, Self-Hosting, #Tech Scratchpad: Appunti avanzati e esperimenti per esperti e amatoriali *Testato il:* 2026-07-29 *Ambiente:* macOS 15.5 · Docker 27.3.1 · Claude Code 2.1.220 ## Prerequisiti - *Docker* e *Docker Compose* installati e funzionanti - Almeno un *agente CLI* nel PATH: Claude Code (`claude`), Codex (`codex`), CodeBuddy, GitHub Copilot CLI, OpenCode, Pi, Cursor Agent o uno degli altri supportati - *Git* per clonare il repository - *Homebrew* (macOS/Linux) per installare la CLI, oppure `curl` per lo script di installazione - Almeno 4 GB di RAM liberi per i container (backend Go + frontend Next.js + PostgreSQL 17) ## 1\. Installa la CLI di Multica La CLI `multica` è il punto di contatto tra la tua macchina e il server Multica. La installi una volta e con quella gestisci workspace, issue, daemon e autenticazione. ```bash brew install multica-ai/tap/multica ``` Se non usi Homebrew, puoi usare lo script di installazione: ```bash curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash ``` Controlla che l'installazione sia riuscita: ```bash multica version ``` Vedrai un output simile a: ```text multica version 0.5.0 (commit: a1b2c3d) ``` ## 2\. Avvia Multica in self-hosting con Docker Tre container: backend Go, frontend Next.js e PostgreSQL 17 con pgvector. Il `Makefile` del repository orchestra tutto con un comando. ```bash git clone https://github.com/multica-ai/multica.git cd multica make selfhost ``` `make selfhost` fa diverse cose in automatico: 1. Crea il file `.env` a partire da `.env.example` 2. Genera `JWT_SECRET`, `POSTGRES_PASSWORD` e altri secret casuali 3. Avvia backend, frontend e PostgreSQL via Docker Compose I container partono in sequenza. Al termine: - *Frontend:* `http://localhost:3000` - *Backend API:* `http://localhost:8080` Immagini pre-buildate — Il comando usa le immagini pre-buildate da GHCR (\`ghcr.io/multica-ai/multica-backend\` e \`ghcr.io/multica-ai/multica-web\`). Se il tag selezionato non è ancora stato pubblicato, \`make selfhost\` ti avviserà e ti suggerirà di usare \`make selfhost-build\` per fare la build in locale. ## 3\. Effettua il login sull'istanza self-host Apri `http://localhost:3000` nel browser. Con `APP_ENV=production` e senza `RESEND_API_KEY`, il codice di verifica per il login non arriva via email: viene stampato nei log del container backend. Per recuperarlo, apri un altro terminale e cerca la riga `[DEV] Verification code` nei log: ```bash docker compose -f docker-compose.selfhost.yml logs -f backend | grep "Verification code" ``` Vedrai una riga simile a: ```text [DEV] Verification code for test@example.com: 4F8A2C ``` Inserisci l'email e il codice nella schermata di login. Sei dentro. In produzione serve RESEND\_API\_KEY — Senza \`RESEND\_API\_KEY\` configurata, il codice di verifica viene stampato solo nei log del container: va bene per lo sviluppo, ma è impraticabile per un team. In produzione, configura una chiave API Resend o un relay SMTP nel \`.env\`. ### In alternativa: codice deterministico per test locali Per i test locali, se vuoi un codice fisso, modifica `.env`: ```bash APP_ENV=development MULTICA_DEV_VERIFICATION_CODE=888888 ``` Poi riavvia i container: ```bash docker compose -f docker-compose.selfhost.yml restart backend ``` Mai su istanze pubbliche — Su un'istanza pubblica \*\*non usare\*\* \`MULTICA\_DEV\_VERIFICATION\_CODE\`: chiunque conosca un indirizzo email potrebbe accedere senza ulteriori verifiche. ## 4\. Configura la CLI e avvia il daemon Collega la CLI alla tua istanza self-host e avvia il daemon. *Resta in background* sulla tua macchina, *rileva automaticamente* gli agent CLI disponibili nel PATH (Claude Code, Codex, CodeBuddy, OpenCode, Pi, Cursor Agent e gli altri) e li registra sul server. Quando un agente riceve un task, è il daemon a eseguirlo in locale. ```bash multica setup self-host ``` Il comando fa tutto in una volta: 1. Configura la CLI per puntare a `localhost:8080` (API) e `localhost:3000` (frontend) 2. Apre il browser per l'autenticazione (dovresti essere già loggato dal passo precedente) 3. Scopre i workspace disponibili 4. Avvia il daemon in background Se pubblichi su un dominio personalizzato invece che su localhost: ```bash multica setup self-host --server-url https://api.example.com --app-url https://app.example.com ``` Verifica che il daemon sia attivo: ```bash multica daemon status ``` Output atteso: ```text Daemon is running (PID: 48291) Uptime: 2m 14s Detected agents: claude, opencode, cursor-agent Watched workspaces: 1 ``` Gli agent rilevati dipendono dalle CLI presenti nel PATH. Se non ne compare nessuno, controlla che almeno `claude` (Claude Code) o un altro agente CLI sia installato e raggiungibile. ## 5\. Crea un agente e assegna il primo task ### 5a. Crea l'agente dall'interfaccia web Vai su `http://localhost:3000`, poi naviga in *Settings → Agents → New Agent*. Scegli: - *Runtime:* il runtime locale che il daemon ha registrato (lo vedi in *Settings → Runtimes*) - *Provider:* uno tra quelli rilevati, ad esempio Claude Code - *Nome:* dai un nome al tuo agente, tipo "Lambda" L'agente compare subito nella lista e può essere assegnato alle issue. ### 5b. Crea un'issue e assegnala all'agente Puoi creare un'issue dalla board nell'interfaccia web, oppure da CLI: ```bash multica issue create \ --title "Aggiungere test per il modulo auth" \ --description "Scrivere unit test per il modulo di autenticazione coprendo login, logout e refresh token" \ --priority high \ --assignee "Lambda" ``` Output atteso: ```text Created issue MUL-1: Aggiungere test per il modulo auth Priority: high Status: todo Assignee: Lambda ``` L'agente prende in carico il task automaticamente: il daemon lo rileva al prossimo poll (*ogni 3 secondi di default*), prepara una directory di lavoro isolata, lancia il CLI dell'agente e inizia a riportare progressi via WebSocket. Sulla board lo stato passa da `todo` a `in_progress` e nella timeline compaiono commenti e aggiornamenti dell'agente. ### Altri comandi CLI utili ```bash multica issue list --status todo # Elenca le issue in stato "todo" multica issue get MUL-1 # Dettaglio di un'issue multica workspace list # Elenca i workspace (quello attivo ha *) multica workspace switch # Cambia workspace predefinito multica agent list # Elenca gli agent nel workspace corrente multica daemon stop # Ferma il daemon multica daemon logs -f # Segui i log del daemon in tempo reale multica auth status # Mostra server, utente e validità del token ``` ## Verifica Per verificare: 1. *Daemon attivo:* `multica daemon status` mostra PID, uptime e agent rilevati 2. *Agente visibile:* nella web app, *Settings → Agents* elenca l'agente che hai creato 3. *Runtime connesso:* *Settings → Runtimes* mostra la tua macchina come attiva 4. *Task in esecuzione:* crea un'issue, assegnala all'agente e verifica che dopo qualche secondo lo stato passi a `in_progress` con commenti nella timeline 5. *Log del daemon:* `multica daemon logs -n 50` mostra l'attività recente Se l'agente non prende il task, controlla i log del daemon (`multica daemon logs -f`) e verifica che il CLI dell'agente sia funzionante lanciandolo direttamente nel terminale (es. `claude --version`). ## Cosa puoi fare da qui Multica ha altre funzionalità oltre all'assegnazione base dei task: - *Squads:* raggruppa agent e umani sotto un leader agent. Assegni lavoro alla squadra (`@FrontendTeam`) e il leader decide chi lo prende in carico - *Autopilots:* lavoro ricorrente schedulato via cron o webhook. L'autopilot crea l'issue e la assegna automaticamente - *Skills:* ogni soluzione prodotta da un agente diventa una skill riutilizzabile dall'intero team - *Multi-Workspace:* isolamento completo per team diversi, ciascuno con i propri agent, issue e impostazioni ## Limiti noti - *La piattaforma è in evoluzione rapida:* il repository ha oltre 42.500 stelle su GitHub e uno sviluppo molto attivo. Comandi e opzioni possono cambiare tra una release e l'altra. Tieni d'occhio i [release notes](https://github.com/multica-ai/multica/releases?ref=adrianoamalfi.com) quando aggiorni. - *Dipendenze dagli agent CLI:* ogni agente (Claude Code, Codex, CodeBuddy, Copilot CLI, OpenCode, Pi, Cursor Agent e gli altri) deve essere installato e funzionante indipendentemente. Se `claude` non è nel PATH, il daemon non lo rileverà e non potrai creare agent basati su Claude Code. - *Il self-hosting richiede risorse:* i tre container (backend Go, frontend Next.js, PostgreSQL 17 con pgvector) consumano RAM e CPU. Su macchine con meno di 8 GB di RAM totale, Docker potrebbe andare in swapping durante build o esecuzioni pesanti. - *Alcuni agent CLI hanno community più piccole:* Kimi, Kiro CLI, Qoder CLI e Trae CLI sono supportati ma potrebbero richiedere configurazione aggiuntiva o chiavi API specifiche del provider. - *Il login senza RESEND\_API\_KEY richiede un passaggio manuale:* recuperare il codice dai log del container backend è comodo per il testing ma scomodo per un team. In produzione configura una chiave API Resend o un relay SMTP nel file `.env`.