KiroCrew su VPS: gateway sempre attivo con Docker

Perché eseguire KiroCrew su un VPS invece che su un laptop

L'hosting autonomo di KiroCrew è utile solo su una macchina che non va mai in sospensione. Per questo un VPS è la scelta corretta, mentre un laptop non lo è. KiroCrew salva su disco la cronologia delle sessioni, la memoria semantica, i job pianificati e la coda delle approvazioni. Ricarica tutti questi dati quando il processo viene riavviato. Questi dati non servono se il processo non è in esecuzione alle 03:00, quando deve essere eseguito un job pianificato. Un laptop chiuso non esegue il processo.

KiroCrew è un workspace per agenti open source del team Kiro, distribuito con licenza Apache 2.0. Le prime release pubbliche sono state pubblicate all'inizio di agosto 2026. Un unico processo, chiamato gateway, gestisce lo stato e rende disponibile una dashboard web sulla porta 5476. Puoi raggiungere il gateway dalla dashboard, dalla kirocrew CLI o da un canale di chat come Slack. Il gateway è l'unico componente che devi eseguire in hosting autonomo. Questa guida spiega quindi come mantenerlo in esecuzione, come non esporlo a Internet e come ripristinarlo dopo un aggiornamento non riuscito.

Prima di iniziare devi sapere due cose. KiroCrew utilizza kiro-cli, che richiede un accesso iniziale con un account Kiro. Inoltre, l'inferenza dell'agente viene addebitata a un piano Kiro. Ad agosto 2026, quindi, questa non è una configurazione offline. Il progetto ha inoltre solo poche settimane di vita. Presupponi che prima o poi dovrai eseguire un rollback e installalo in modo da poterlo fare. Se non hai mai eseguito un agente su un server, eseguire un agente di coding su un VPS descrive i principi di base su cui si fonda questa guida.

Cosa richiede KiroCrew e dove risiede il suo stato

Un'installazione nativa richiede Python 3.10 o versione successiva (il progetto consiglia la 3.12), Node.js 18 o versione successiva se si compila la dashboard dal codice sorgente e kiro-cli, che viene installato e configurato al primo avvio. L'installazione in un container non richiede nulla di tutto questo sull'host. Richiede Docker. Questo è il motivo principale per preferirla.

Lo stato risiede in ~/.kiro/crew e la variabile d'ambiente KIROCREW_HOME consente di spostarlo altrove. Il contenuto include:

• config.json: impostazioni del gateway e credenziali dei canali di chat.
• .env: secret.
• workspace/memory/: preferenze, note sui progetti e cronologia delle chat.
• memory.db e memory_index.db: gli indici semantico e full-text.
• models/: il modello di embedding, scaricato al primo avvio.
• gateway.log e security_events.jsonl: il log di runtime e il log degli eventi di sicurezza.

Quella directory è l'installazione. Copiala su un nuovo VPS e avrai spostato il tuo agente. Per questo la sezione sul backup riportata di seguito è più importante di quella sull'installazione.

Pianifica lo spazio su disco, non la RAM. Il gateway è un processo Python; ciò che carica realmente il server sono le attività eseguite dall'agente, ad esempio una compilazione o una suite di test. La directory dello stato cresce con la cronologia delle chat e il modello di embedding viene scaricato al primo avvio. Dopo alcune settimane, misurala sul tuo server con du -sh ~/.kiro/crew invece di affidarti a dati pubblicati durante il primo mese di vita di un progetto.

Quale dei tre percorsi di installazione utilizzare

Il progetto ne pubblica tre. L’installer su una riga scarica un wheel e inserisce kirocrew nel PATH:

curl -fsSL https://download.crew.kiro.dev/cli.sh | sh

Accetta un flag per il canale e un flag per la versione:

curl -fsSL https://download.crew.kiro.dev/cli.sh | sh -s -- --channel insider
curl -fsSL https://download.crew.kiro.dev/cli.sh | sh -s -- --version 0.1.3

L’immagine container è pubblicata in ghcr.io/kirodotdev/kirocrew, per linux/amd64 e linux/arm64 con ogni tag. La build dal codice sorgente richiede git clone e make build ed è destinata a chi modifica il codice, non a chi esegue il software.

Utilizza il container. Un’installazione nativa colloca i pacchetti Python, Node e kiro-cli sullo stesso host che esegue gli altri servizi. Se un aggiornamento non riesce, devi quindi risolvere manualmente le conseguenze. Il container mantiene il runtime in un’unica immagine e lo stato in un unico volume. In questo modo, per eseguire il rollback, basta cambiare tag e riavviare.

Blocca l’immagine su un tag di release, non su stable

L’esempio del progetto usa il tag stable:

docker run -d --name kirocrew \
  -p 127.0.0.1:5476:5476 \
  -v kirocrew-home:/home/kirocrew \
  ghcr.io/kirodotdev/kirocrew:stable

stable è un tag mobile. Punta alla release stabile più recente disponibile, quindi il pull successivo può modificare la versione in esecuzione senza una scelta esplicita da parte tua. Inoltre, il tag non registra quale versione fosse in uso. I tag di versione sono immutabili, quindi utilizzane uno. La release più recente al 6 agosto 2026 è 0.1.3, pubblicata il 5 agosto 2026. Esiste anche il tag nightly, ma in un progetto così recente significa che il codice è cambiato questa mattina.

Scrivi /opt/kirocrew/compose.yaml:

services:
  kirocrew:
    image: ghcr.io/kirodotdev/kirocrew:0.1.3
    container_name: kirocrew
    restart: unless-stopped
    ports:
      - "127.0.0.1:5476:5476"
    volumes:
      - kirocrew-home:/home/kirocrew

volumes:
  kirocrew-home:

Avvialo, quindi controlla l’endpoint di health check utilizzato dall’immagine anche per il proprio HEALTHCHECK:

cd /opt/kirocrew
docker compose up -d
docker compose ps
curl -s http://127.0.0.1:5476/api/health

docker compose ps dovrebbe indicare il container come integro entro circa un minuto e /api/health risponde senza token, così come /api/live e /api/ready, condizione che li rende utilizzabili come probe. Se lo stato rimane starting, leggi docker logs kirocrew prima di modificare qualsiasi cosa. Al primo avvio viene scaricato il modello di embedding, quindi una connessione lenta può allungare sensibilmente l’avvio iniziale.

Mantenerlo in esecuzione con systemd

restart: unless-stopped riavvia il container dopo un arresto anomalo e dopo un riavvio, purché Docker venga avviato all'avvio del sistema. Un file unit rende esplicita questa dipendenza e fornisce un unico comando per arrestare l'intero stack prima di un backup. Avviare uno stack Docker Compose all'avvio descrive il modello generale. Per KiroCrew, la configurazione è questa, in /etc/systemd/system/kirocrew.service:

[Unit]
Description=KiroCrew gateway
Requires=docker.service
After=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/opt/kirocrew
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down
TimeoutStartSec=0

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now kirocrew
systemctl status kirocrew

systemctl status kirocrew dovrebbe restituire active (exited), che è il risultato corretto per questa unit. Type=oneshot con RemainAfterExit=yes è appropriato in questo caso perché docker compose up -d restituisce il controllo non appena il container viene avviato: systemd tiene traccia del fatto che lo stack è attivo, non di un processo in primo piano. Se si scrive invece Type=simple, systemd vede che il comando termina immediatamente, contrassegna il servizio come arrestato e poi rinuncia oppure entra in un ciclo di riavvio, a seconda dell'impostazione Restart=. Per un'installazione nativa, il progetto fornisce un equivalente specifico, kirocrew service install, che scrive /etc/systemd/system/kirocrew.service e avvia il gateway con il proprio account utente. Non eseguire entrambe le unit. La trattazione più ampia di questo argomento è disponibile in servizi e timer systemd su un VPS.

Prima esecuzione: accedi e ottieni un token per la dashboard

Il container avvia il gateway, ma il runtime dell’agente non ha ancora effettuato l’accesso. Accedi all’interno del container:

docker exec -it kirocrew kiro-cli login

Il comando visualizza un codice dispositivo e un URL da aprire nel browser locale. Genera quindi un token per la dashboard:

docker exec kirocrew kirocrew token --ttl 2h

L’URL della dashboard è http://localhost:5476/?token=<the token>. I token scadono: per impostazione predefinita, le sessioni durano un’ora e il limite massimo documentato è di venti ore. Se la dashboard viene caricata vuota o ti reindirizza immediatamente alla pagina di accesso, nella maggior parte dei casi il token è scaduto; generane quindi un altro. Non incollare mai un token in un ticket o in un messaggio di chat, perché chiunque ne entri in possesso controlla il tuo agente.

Accedere alla dashboard tramite SSH senza pubblicare la porta 5476

Controlla nuovamente l'indirizzo di bind nell'esempio del progetto: -p 127.0.0.1:5476:5476. All'interno del container il gateway è in ascolto su 0.0.0.0, perché deve essere raggiungibile tramite il port mapping, ma il mapping pubblica il servizio soltanto sull'interfaccia loopback dell'host. Elimina il prefisso 127.0.0.1: e il gateway sarà esposto su Internet a chiunque esegua una scansione di quella porta. Una regola del firewall non è sufficiente: Docker pubblica le porte creando regole DNAT, valutate prima dei filtri di ufw, quindi ufw deny 5476 non ha effetto su una porta pubblicata. Porte Docker che bypassano ufw illustra questo meccanismo.

Inoltra invece la porta tramite SSH dal laptop:

ssh -N -L 5476:127.0.0.1:5476 you@your-server.example.com

Lascia il comando in esecuzione e apri http://localhost:5476/?token=<the token> in locale. Per attivare automaticamente il forwarding a ogni connessione, inseriscilo in ~/.ssh/config:

Host your-server.example.com
    LocalForward 5476 127.0.0.1:5476

Se la porta 5476 è già in uso sul laptop, modifica soltanto il numero a sinistra: ssh -N -L 45476:127.0.0.1:5476 you@your-server.example.com, quindi apri http://localhost:45476/?token=... nel browser.

Durante l'uso del tunnel si verifica un comportamento documentato: il gateway considera remote le richieste inoltrate, quindi la dashboard rifiuta gli endpoint per la scrittura della configurazione e la visualizzazione dei secret. Se una modifica alle impostazioni non viene salvata tramite SSH, questo è il motivo; non si tratta di un bug. Modifica invece la configurazione direttamente sull'host:

docker cp kirocrew:/home/kirocrew/.kiro/crew/config.json .
# edit config.json here
docker cp config.json kirocrew:/home/kirocrew/.kiro/crew/config.json
docker exec -u 0 kirocrew chown kirocrew:kirocrew /home/kirocrew/.kiro/crew/config.json
docker restart kirocrew

Per l'accesso da telefono, il progetto indica tailscale serve di Tailscale, che mantiene la dashboard all'interno del tuo tailnet invece di esporla tramite un hostname pubblico. È preferibile a un reverse proxy pubblico. Il token viene trasmesso nell'URL e l'URL viene scritto in ogni access log attraversato dalla richiesta.

Assegna all'agente il raggio d'azione più limitato possibile

Il container verifica il supporto alla sandbox al primo avvio. Il risultato determina se gli agenti possono eseguire operazioni. Se l'isolamento tramite namespace è disponibile, i processi secondari dell'agente vengono eseguiti in isolamento. Se non è disponibile e KIROCREW_ALLOW_UNSANDBOXED=1 non è impostato, l'esecuzione viene rifiutata invece di procedere senza isolamento. Per questo, quando il gateway sembra funzionare ma ogni attività resta bloccata, questa è di solito la causa. La decisione viene registrata in docker logs kirocrew durante quella prima esecuzione. Il progetto pubblica anche un profilo seccomp (secure computing mode) che puoi applicare:

curl -fsSL https://raw.githubusercontent.com/kirodotdev/KiroCrew/main/docker/seccomp/kirocrew-seccomp.json \
  -o /opt/kirocrew/kirocrew-seccomp.json

    security_opt:
      - seccomp:./kirocrew-seccomp.json

Se imposti KIROCREW_ALLOW_UNSANDBOXED=1, chiarisci cosa cambia: il container diventa l'unico confine tra l'agente e il server. Vale la pena ripetere integralmente l'avvertenza del progetto. Non montare percorsi dell'host che non consegneresti direttamente all'agente. In pratica, questo esclude il socket Docker, qualsiasi bind mount di / e qualsiasi directory che contiene i dati di un altro servizio.

Il resto costituisce la configurazione di base da applicare a ogni agente autorizzato a eseguire comandi. Limita le sue credenziali al singolo repository o al singolo bucket di cui ha bisogno. Non usare mai un token personale con autorizzazioni sull'intero account. Eseguilo con un utente dedicato, la cui home non contenga altro: è questo lo scopo di utenti con privilegi minimi su un VPS. Quando l'agente scrive codice e poi lo esegue, assegnagli una macchina che possa danneggiare: una VM temporanea per gli agenti di coding offre un confine più solido di qualsiasi flag in questo compose file, perché puoi eliminarla invece di ripulirla. Lo stesso principio si applica a eseguire OpenClaw in sicurezza su un VPS e a self-hosting dell'agente Hermes su un VPS. Anche gli strumenti contribuiscono al raggio d'azione: fornire all'agente la ricerca web trasforma ogni pagina recuperata in input non attendibile. Per questo indirizzarlo verso la propria istanza SearXNG è una decisione legata alla prompt injection tanto quanto alla configurazione del collegamento. Le attività pianificate consumano denaro anche mentre dormi, perché l'inferenza viene addebitata al tuo piano Kiro. Imposta quindi i limiti descritti in controllare i costi di un agente AI su un VPS prima di aggiungere un'attività notturna.

Esegui il backup del volume di stato prima di ogni aggiornamento

Individua prima il nome reale del volume. Compose antepone ai volumi denominati il nome del progetto, che per impostazione predefinita corrisponde al nome della directory. Il volume dichiarato come kirocrew-home in /opt/kirocrew/compose.yaml viene quindi creato come kirocrew_kirocrew-home:

docker volume ls

Arresta il gateway prima di copiare qualsiasi file. memory.db e memory_index.db sono database SQLite. Copiare un database mentre è in fase di scrittura può acquisire una transazione incompleta, che durante il ripristino produce un file corrotto. Le istruzioni di migrazione del progetto indicano la stessa procedura: sposta la memoria solo quando i gateway sono arrestati.

sudo systemctl stop kirocrew
docker run --rm -v kirocrew_kirocrew-home:/data:ro -v "$PWD":/backup \
  alpine tar czf /backup/kirocrew-2026-08-06.tgz -C /data .
sudo systemctl start kirocrew

Copia l'archivio fuori dal server. Per il ripristino usa lo stesso comando, con il container arrestato e tar xzf al posto di tar czf:

sudo systemctl stop kirocrew
docker run --rm -v kirocrew_kirocrew-home:/data -v "$PWD":/backup \
  alpine tar xzf /backup/kirocrew-2026-08-06.tgz -C /data
sudo systemctl start kirocrew

La migrazione a un nuovo host è diversa da un ripristino sullo stesso host e il progetto specifica come procedere. La cronologia delle chat e le note del progetto in workspace/memory/ vengono trasferite, così come i due file di database e config.json. I file PID, il log degli eventi di sicurezza e .env sono legati al vecchio host. Lasciali quindi sul vecchio sistema e inserisci nuovamente i secret sul nuovo server.

Come si esegue il rollback dopo un aggiornamento errato

L'aggiornamento è rapido ed è sicuro solo perché hai bloccato una versione. Crea prima il backup, quindi modifica il tag:

sudo systemctl stop kirocrew
# take the backup here, as above
sudo nano /opt/kirocrew/compose.yaml   # set the new image tag
sudo systemctl start kirocrew
docker compose -f /opt/kirocrew/compose.yaml ps
curl -s http://127.0.0.1:5476/api/health

docker compose up -d scarica l'immagine se non è già presente sul server, quindi per eseguire l'aggiornamento è sufficiente modificare il tag. Il rollback segue la stessa sequenza usando il numero precedente e ripristina esattamente l'immagine disponibile prima dell'aggiornamento, perché i tag delle versioni sono immutabili.

Il binario torna alla versione precedente senza problemi. Il problema può riguardare lo stato. Un gateway più recente può riscrivere config.json o migrare i database in memoria in un formato che un gateway precedente non riesce a leggere; ad agosto 2026 non è documentata alcuna procedura di downgrade. Se quindi l'immagine precedente si avvia ma si comporta in modo anomalo, non eseguire il debug. Arrestala, ripristina il backup creato prima dell'aggiornamento e riparti. Questo è il motivo per cui il backup viene creato prima dell'aggiornamento e per cui, in un progetto così recente, l'abitudine di aggiornare subito e creare il backup dopo non è affidabile.

Cosa non è dimostrato in questo documento

Siate trasparenti sull'età di questo software. La versione 0.1.3 ha pochi giorni al momento della stesura, le relative note di rilascio sono link automatizzati a un changelog e non note sulle migrazioni, e non esiste ancora uno storico degli aggiornamenti. Nulla in questa guida è un risultato a lungo termine. Considerate quindi la crescita della memoria, le dimensioni del database e l'affidabilità dello scheduler come aspetti da misurare sul vostro server, non come comportamenti da dare per scontati.

Prima di affidarvi a questi comportamenti, è opportuno verificarne personalmente due. Per prima cosa, controllate se un downgrade legge lo stato scritto da una versione più recente. Eseguite la prova su una copia del volume, quando un eventuale problema non ha conseguenze, non durante un'interruzione del servizio. Verificate poi come si comporta il gateway quando l'accesso a Kiro scade mentre è previsto un job pianificato. Sono entrambi potenziali problemi di un progetto giovane, che possono essere risolti silenziosamente tra una release e l'altra. In entrambi i casi, una verifica preventiva richiede poco tempo.

FAQ

Perché la dashboard di KiroCrew non si apre sull'indirizzo IP pubblico del mio server?

Perché l'esempio pubblicato associa la porta all'interfaccia loopback. -p 127.0.0.1:5476:5476 associa la porta del container solo all'indirizzo loopback dell'host, intenzionalmente. Per raggiungerla, inoltra la porta tramite SSH con ssh -N -L 5476:127.0.0.1:5476 you@your-server, quindi apri http://localhost:5476/?token=<token> sul tuo laptop. Rimuovere il prefisso 127.0.0.1: per renderla raggiungibile espone il gateway su Internet pubblico. Una regola del firewall non sarebbe sufficiente, perché le regole DNAT delle porte pubblicate da Docker vengono valutate prima che ufw filtri il traffico.

Dove salva i dati KiroCrew e di cosa devo eseguire il backup?

Tutto si trova in ~/.kiro/crew, che corrisponde a /home/kirocrew/.kiro/crew all'interno dell'immagine del container, mentre KIROCREW_HOME lo sposta. Esegui il backup dell'intera directory o dell'intero volume Docker, con il gateway arrestato. memory.db e memory_index.db sono database SQLite. Una copia eseguita mentre il gateway scrive può quindi risultare incoerente. Quando esegui la migrazione su un nuovo host, workspace/memory/, i due file di database e config.json vengono trasferiti, mentre i file PID, il log degli eventi di sicurezza e .env appartengono al vecchio host.

Devo usare il tag stable o un tag di versione?

Usa un tag di versione. stable cambia ogni volta che viene rilasciata una nuova versione. La versione in esecuzione può quindi cambiare al pull successivo e il tag, da solo, non indica quale versione sia in esecuzione. I tag di versione come 0.1.3 sono immutabili. Questo è ciò che rende possibile un rollback: ripristini il numero precedente e ottieni un'immagine identica. Al 6 agosto 2026, la versione più recente è 0.1.3.

Perché il mio agent rifiuta di eseguire qualsiasi comando?

Il container verifica il supporto per la sandbox al primo avvio. Se non riesce a isolare i sottoprocessi dell'agent e KIROCREW_ALLOW_UNSANDBOXED=1 non è impostata, rifiuta di eseguirli invece di avviarli senza isolamento. Il gateway risulta quindi operativo, mentre ogni attività rimane bloccata. docker logs kirocrew mostra la decisione relativa alla sandbox presa durante quella prima esecuzione. Impostando la variabile, il container diventa l'unica barriera tra l'agent e l'host. Se la imposti, monta soltanto ciò che consegneresti direttamente all'agent.

Ho bisogno di un account Kiro per eseguire il self-hosting di KiroCrew?

Sì, ad agosto 2026. KiroCrew è software libero distribuito con licenza Apache 2.0, ma utilizza kiro-cli, che richiede un accesso iniziale una tantum, e l'inferenza dell'agent viene addebitata a un piano Kiro. Nel container, esegui docker exec -it kirocrew kiro-cli login e approva il codice del dispositivo nel browser. Finché l'accesso non viene completato, il gateway si avvia e la dashboard viene caricata, ma l'agent non dispone di alcun modello con cui comunicare.