Multica: installare e usare la piattaforma open-source per managed agents

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.

brew install multica-ai/tap/multica

Se non usi Homebrew, puoi usare lo script di installazione:

curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash

Controlla che l'installazione sia riuscita:

multica version

Vedrai un output simile a:

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.

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

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:

docker compose -f docker-compose.selfhost.yml logs -f backend | grep "Verification code"

Vedrai una riga simile a:

[DEV] Verification code for [email protected]: 4F8A2C

Inserisci l'email e il codice nella schermata di login. Sei dentro.

In alternativa: codice deterministico per test locali

Per i test locali, se vuoi un codice fisso, modifica .env:

APP_ENV=development
MULTICA_DEV_VERIFICATION_CODE=888888

Poi riavvia i container:

docker compose -f docker-compose.selfhost.yml restart backend

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.

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:

multica setup self-host --server-url https://api.example.com --app-url https://app.example.com

Verifica che il daemon sia attivo:

multica daemon status

Output atteso:

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:

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:

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

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 <id|slug>      # 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 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.