Aggiungi un host

Un host è una macchina dove girano gli agenti. È un container che si collega in uscita al server con un WebSocket, quindi funziona dietro NAT senza porte aperte, e non tiene niente di tuo: un volume di cache (copie dei repository, motori installati, il suo token) e, per ogni run, una cartella in memoria che sparisce alla fine. Perdere un host fa perdere solo i run che aveva in corso.

Il primo host

L’installer e il file per Coolify avviano un host accanto al server. Entra da solo appena il tuo account esiste, con il codice monouso scritto nel .env dell’installazione. Raggiunge il server dalla rete di compose, non da internet.

Un altro host

Nell’app, Sistema → Host elenca i tuoi host con il loro stato (in linea o no, ultimo contatto, run al lavoro, sandbox, versione).

Prendi la riga. Premi Aggiungi host. La pagina crea un codice d’ingresso e mostra la riga docker run che lo porta, con Copia e un conto alla rovescia: il codice vale una volta, per dieci minuti. Se il server non conosce l’immagine dell’host, la pagina dice di costruirla prima dal clone (docker build -f apps/host/image/Dockerfile -t kedalio-host:local .).
Sulla nuova macchina, lancia la riga in una shell (bash o sh). Serve solo Docker, nessun clone: legge il profilo seccomp dall’immagine dell’host e poi cancella il file temporaneo. Su una macchina con AppArmor si usa il profilo dell’host se è installato (/etc/apparmor.d/kedalio-host, vedi sotto); senza, vale il profilo di Docker, che vieta i mount che la sandbox richiede: l’host parte, dice che la sandbox è fallita e non prende run.
Oppure usa il file compose, da un clone, apps/host/image/, per dare un nome all’host e far costruire l’immagine a Compose:
Finestra del terminale
```
KEDALIO_SERVER=https://app.example.com KEDALIO_JOIN=<codice> KEDALIO_NAME=box2 docker compose up -d
```
KEDALIO_HOST_IMAGE dice quale immagine usare; senza, Compose la costruisce dal clone. Il nome è fatto di lettere, cifre, ., _ e -, al massimo 63; senza nome si usa l’hostname del container.

L’host scambia il codice con un token suo, lo tiene nel volume di cache e da lì in poi parte senza KEDALIO_JOIN. Un host avviato senza token e senza codice si ferma e dice: no host token in … and no KEDALIO_JOIN: add the host from the app.

La sandbox

Ogni agente gira in una sandbox dentro il container: Claude Code con la sua, che non può spegnere, OpenCode e Pi in una gabbia bubblewrap. Per questo il container vuole le sue opzioni di sicurezza: nessuna capability, no-new-privileges, un profilo seccomp che è quello di Docker più le chiamate che servono a bubblewrap, systempaths=unconfined e, su una macchina con AppArmor, il profilo dell’host. Per installarlo, da apps/host/image/ di un clone, una volta:

sudo install -m 0644 apparmor/kedalio-host /etc/apparmor.d/kedalio-host
sudo apparmor_parser -r -W /etc/apparmor.d/kedalio-host

L’host controlla la sandbox all’avvio e ogni ora; se il controllo fallisce non prende run. Puoi fare lo stesso controllo a mano:

docker run --rm --cap-drop ALL --security-opt no-new-privileges \
  --security-opt seccomp=seccomp.json --security-opt systempaths=unconfined <immagine host> probe

sandbox: ok è quello che serve a un host.

Un run non legge mai il token dell’host e fa il push solo del suo ramo, kedalio/<run-id>: mai main, master, dev, beta o release, mai una cancellazione.

Quanti run prende un host

La capacità viene dalla memoria del container: (memoria − 2 GiB) ÷ 1,5 GiB sessioni, almeno una. Il file compose dell’host dà 8 GB (4 sessioni) e 4 CPU di default; li cambi con KEDALIO_HOST_MEMORY e KEDALIO_HOST_CPUS, gli stessi nomi dei file del server (KEDALIO_MEMORY e KEDALIO_CPUS, i nomi di prima, funzionano ancora).

Un host può anche rifiutare lavoro, qualunque cosa dica il server:

Variabile	Cosa rifiuta l’host
`KEDALIO_ALLOW_REPOS`	i repository fuori dalla lista, `host/owner` o `host/owner/repo`, separati da virgole
`KEDALIO_ALLOW_ENGINES`	i motori fuori dalla lista: `claude-code`, `codex`, `opencode`, `pi`
`KEDALIO_MAX_RUNS`	più run insieme di questo numero

Un run nuovo va a un host in linea con la sandbox a posto, che ha il motore, è dentro i suoi limiti e ha una sessione libera; tra questi, quello con più spazio. Una squadra che indica il suo host lo aspetta.

Aggiornamenti

Gli host seguono da soli la versione del server. Quando il server dice quale versione vuole, l’host ne scarica il pacchetto dal server, ne controlla lo SHA-256, aspetta che non ci siano run in corso e riparte su quello. I motori si installano nella cache alle versioni che il server fissa (nel suo codice; KEDALIO_ENGINES lo cambia). Un’immagine nuova dell’host, con pacchetti di sistema più recenti, arriva ancora solo scaricando di nuovo l’immagine.

Offline, rientrare, rimuovere

Un host manda un battito ogni 20 secondi e si ricollega da solo. Il server stacca un host muto da un minuto; i suoi run si interrompono dopo dieci minuti offline.
Rientrare con un codice nuovo e lo stesso nome tiene l’host e ne sostituisce il token. Un host di cui il server non accetta più il token (revocato) lo cancella e rientra da solo se ha KEDALIO_JOIN; senza, scrive nel log che è stato revocato e vuole un codice nuovo, e smette di riprovare. Un token che il server accetta ancora vince su KEDALIO_JOIN.
Rimuovere un host è Revoca sulla sua riga in Sistema → Host. L’host va subito offline, i suoi run non vengono più riportati e il suo token smette subito di funzionare; fermare il container tocca a te.

Non ancora costruito: «usa questo computer come host» in un’app desktop.