SSD Nodes Learn Hosting plans →
Guide Matt ConnorDi Matt Connor

Come fare il self-hosting di OneCLI con Docker

OneCLI assegna un agent isolato a ogni persona e conserva le chiavi in un gateway. Guida con Docker Compose, PostgreSQL e dimensionamento: 2 GiB per sandbox.

Cosa si ottiene con il self-hosting di OneCLI

Con il self-hosting di OneCLI, ogni persona del team dispone del proprio agent, eseguito in un sandbox separato. Le API key sono custodite in un gateway che gli agent non possono leggere. L'installazione è uno stack Docker Compose con PostgreSQL, raggiungibile su http://localhost:10254. È necessario prevedere un server adeguato. La configurazione predefinita documentata assegna un limite di memoria di 2 GiB a ogni sandbox dell'agent. Occorre quindi considerare separatamente la memoria richiesta dallo stack di base e quella effettivamente utilizzata dagli agent.

Lo stack include otto componenti. Capire il ruolo di ciascuno rende più semplice seguire il resto della guida.

  • Dashboard web (Next.js), porta 10254. Creazione degli agent, chat, modifica della memoria e delle skill, connessioni e secret.
  • Server API, porta 10256. Il control plane: database, gestione delle conversazioni e code di lavoro.
  • Gateway Rust, porta 10255. Intercetta le richieste in uscita degli agent e inserisce le credenziali.
  • Runner. Il README lo descrive come il componente che "avvia, sospende e rimuove i sandbox degli agent. Solo in uscita e senza mai accedere al database."
  • Sandbox Supervisor. Il README lo descrive come il componente eseguito "all'interno di ogni sandbox, che comunica tramite un'interfaccia harness indipendente dal fornitore, in modo da poter sostituire il runtime dell'agent."
  • Terminatore SSH, porta 10257. Il README lo definisce "il punto di accesso SSH": termina le connessioni SSH usando certificati a breve durata emessi dall'API e inoltra ogni sessione al sandbox di un agent. Viene eseguito con lo stesso profilo runner del runner.
  • Channel adapter. Un daemon che connette un'app Slack, in modo che un agent possa rispondere nei canali e nei messaggi diretti con il proprio nome.
  • PostgreSQL. Il file Compose fornito esegue postgres:18-alpine con un volume pgdata.

Il nome suggerisce una CLI, ma il prodotto è un server

OneCLI è una piattaforma server. Il nome fa pensare a uno strumento da riga di comando da installare su un laptop, ma questa descrizione non corrisponde al componente illustrato in questa guida. Esiste un client separato da riga di comando nel repository onecli/onecli-cli, che instrada il traffico di un agente di coding locale attraverso un gateway. Qui viene distribuita un'applicazione web multiutente: un sistema di account con organizzazioni e inviti, un database di conversazioni e secret e un runner che avvia container.

Il modello per persona è alla base dell'intero progetto. Come indicato nel README: "Create an agent per person, give each agent the access it needs, and it works in a sandbox, routed through a gateway that injects the credentials and enforces your policy." Ogni agente dispone di un filesystem e di una shell propri, di una pagina di conversazione dedicata, della memoria conservata dalla piattaforma e delle skill definite una sola volta. Le credenziali vengono gestite in modo opposto rispetto alla configurazione consueta. Invece di copiare una chiave API nell'ambiente di ogni persona, si salva la chiave una sola volta e la si assegna agli agenti autorizzati a usarla.

Prerequisiti del server

  • Docker, con il plugin Compose alla versione 2.24.0 o successiva. Il file Compose fornito usa mapping env_file opzionali con required: false, supportati da Docker a partire dalla versione 2.24.0. I commenti sulla migrazione indicano il requisito minimo 2.19 per il supporto delle dipendenze one-shot tramite up --wait, ma questo non copre i file di ambiente opzionali usati dal file.
  • Memoria, che rappresenta il vincolo principale. Leggi la sezione sul dimensionamento più avanti prima di scegliere un piano.
  • Le porte loopback 10254, 10255, 10256, 10257 e 5432 libere. La porta 10257 è l'accesso SSH, che viene avviato con il profilo runner abilitato da questa guida.

Non è necessario installare PostgreSQL manualmente: il file Compose lo avvia come servizio. La procedura guidata di configurazione seguente richiede Node.js e pnpm sull'host. Anche lo sviluppo del codice usa mise per fissare la toolchain, incluso Rust per il gateway.

Quante sandbox degli agenti può ospitare il tuo VPS?

La documentazione del runner fornisce valori concreti, non semplici stime. Ogni sandbox è limitata a 2048 MB di memoria (RUNNER_SANDBOX_MEMORY_MB), una CPU (RUNNER_SANDBOX_CPUS) e 512 processi (RUNNER_SANDBOX_PIDS). Il limite di concorrenza è 4 (RUNNER_MAX_SANDBOXES) e la documentazione consiglia circa 10 GiB di memoria libera oltre allo stack di base per gestire questo limite.

GraficoAgent memory budgets per box, using the documented 2 GiB cap
I dati alla base di questo grafico
[
  {
    "plan": "2 GB box",
    "ram_gb": 2,
    "sandbox_slots": 0
  },
  {
    "plan": "4 GB box",
    "ram_gb": 4,
    "sandbox_slots": 1
  },
  {
    "plan": "8 GB box",
    "ram_gb": 8,
    "sandbox_slots": 3
  },
  {
    "plan": "16 GB box",
    "ram_gb": 16,
    "sandbox_slots": 7
  },
  {
    "plan": "32 GB box",
    "ram_gb": 32,
    "sandbox_slots": 15
  }
]

Questi numeri di slot sono calcoli aritmetici, non risultati di un benchmark: la memoria totale, meno circa 2 GB ipotizzati per PostgreSQL e gli altri servizi a esecuzione continua, divisa per il limite di 2 GiB per sandbox. Su questa base, i budget 2 GB box consentono di eseguire 0 sandbox al loro limite massimo di memoria; zero indica che, secondo queste ipotesi, non c'è memoria sufficiente per nessuna sandbox al limite massimo, non che Docker rifiuti di avviare un agente. Un 16 GB box lascia spazio per 7, quindi supera ampiamente il limite predefinito di quattro e i circa 10 GiB di memoria libera richiesti dalla documentazione del runner. Il 32 GB box consente di arrivare a 15. Per eseguirne più di quattro contemporaneamente è inoltre necessario aumentare RUNNER_MAX_SANDBOXES.

Due fattori modificano questo calcolo. Una sandbox con un processo in background in esecuzione non viene mai sospesa, quindi mantiene permanentemente il proprio slot. Di conseguenza, per un carico prolungato è necessario dimensionare RUNNER_MAX_SANDBOXES, non il valore richiesto durante il minuto di maggiore attività. La piattaforma applica comunque un limite: per impostazione predefinita, ogni runner mantiene attive al massimo RUNNER_MAX_SANDBOXES meno uno sandbox (mai meno di una; il valore può essere modificato con MAX_HELD_AWAKE_SANDBOXES tramite API). Oltre questo limite, il runner espelle la sandbox inattiva da più tempo e segnala come perso il processo monitorato. L'uso di memoria e CPU dipende dal carico di lavoro. Ogni sandbox è limitata a una CPU, quindi quattro agenti sotto carico possono usare quattro core, ma l'impostazione di memoria di 2 GiB è un limite massimo, non una prenotazione: quattro agenti inattivi ma ancora attivi non consumano automaticamente 8 GiB.

Impostazioni del runner che potresti voler modificare
  • RUNNER_MAX_SANDBOXES (predefinito 4): numero di sandbox eseguite contemporaneamente.
  • RUNNER_SANDBOX_MEMORY_MB (predefinito 2048): limite di memoria per sandbox.
  • RUNNER_SANDBOX_CPUS (predefinito 1): limite CPU per sandbox.
  • RUNNER_SANDBOX_PIDS (predefinito 512): limite di processi per sandbox.
  • RUNNER_NETWORK_INTERNAL (predefinito true): mantiene la rete della sandbox senza una route verso l'esterno. Lascialo attivo.
  • RUNNER_SANDBOX_NETWORK (predefinito onecli-sandboxes): rete a cui si connettono le sandbox.
  • RUNNER_RECONCILE_SECONDS (predefinito 60): frequenza con cui il runner riconcilia lo stato.
  • RUNNER_ORPHAN_GRACE_SECONDS (predefinito 3600): tempo trascorso il quale i container e i volumi orfani vengono eliminati.
  • RUNNER_AGENT_IMAGE: sostituisce l'immagine della sandbox, che altrimenti segue ONECLI_VERSION.

Installare OneCLI con Docker Compose

La sequenza grezza della documentazione upstream per il self-hosting scrive tre secret in docker/.env accanto al file Compose. La sequenza non include il token del runner, il gruppo del socket Docker e le credenziali SSH richieste dai servizi che abilita. Eseguire quindi il wizard di configurazione prima di avviare lo stack.

git clone https://github.com/onecli/onecli.git && cd onecli/docker
cat > .env <<EOF
SECRET_ENCRYPTION_KEY=$(head -c 32 /dev/urandom | base64)
GATEWAY_INTERNAL_SECRET=$(head -c 32 /dev/urandom | base64)
BETTER_AUTH_SECRET=$(head -c 32 /dev/urandom | base64)
COMPOSE_PROFILES=runner
EOF
chmod 600 .env
cd ..
pnpm install
pnpm run setup
cd docker
docker compose up -d --wait

Leggere questo blocco prima di eseguirlo. Il marker heredoc non è racchiuso tra virgolette, quindi la shell esegue ogni head -c 32 /dev/urandom | base64 e scrive il risultato invece del testo letterale. SECRET_ENCRYPTION_KEY è la chiave AES-256-GCM per ogni secret presente nel database. GATEWAY_INTERNAL_SECRET autentica il gateway verso l'API. BETTER_AUTH_SECRET firma i cookie di sessione. COMPOSE_PROFILES=runner è la riga più importante, perché il servizio runner è gestito tramite un profilo Compose: se la si omette, lo stack risulta attivo e integro, ma non viene avviato alcun sandbox agent.

--wait attende che i servizi siano in esecuzione o in stato healthy e che la dipendenza dalle migrazioni venga completata correttamente. Un codice di uscita diverso da zero è quindi il primo segnale di un problema. Controllare poi quali servizi sono stati effettivamente avviati.

docker compose ps
docker compose logs migrations

Bloccare la versione. ONECLI_VERSION imposta contemporaneamente il tag per tutti i servizi e l'immagine del sandbox agent lo segue, salvo che RUNNER_AGENT_IMAGE punti altrove. Usare il numero di versione senza prefissi: i tag delle immagini pubblicate non includono il prefisso v. Al 1 novembre 2026 la release corrente è v2.17.0, pubblicata il 31 ottobre 2026. Aggiungerla allo stesso file, quindi usare la procedura di aggiornamento documentata per spostare alla stessa immagine anche i sandbox già in esecuzione.

echo 'ONECLI_VERSION=2.17.0' >> .env
cd ..
pnpm run setup --upgrade
cd docker

È disponibile anche un installer, curl -fsSL https://onecli.sh/install | sh, che scrive la configurazione in ~/.onecli/.env ed esegue le stesse operazioni. Per la propria esecuzione imposta ONECLI_VERSION=latest, sovrascrivendo un pin conservato soltanto nel file .env. Il percorso con Compose consente di leggere ogni file prima dell'avvio ed è quello da usare su un host che esegue già altri stack Compose. La configurazione ottenuta con il checkout precedente viene aggiornata con pnpm run setup --upgrade. Questo percorso richiede Node.js e pnpm sull'host; lavorare direttamente sul codice aggiunge inoltre mise e Rust per il gateway, quindi è adatto a chi intende modificare OneCLI. Per Kubernetes, la release v2.11.0 del 8 ottobre 2026 ha aggiunto un chart Helm. Il chart corrente esegue i sandbox agent come Job con volumi persistenti, senza un daemon Docker, e documenta i secret, il database e la configurazione del routing richiesti.

Accesso alla dashboard dal laptop

Tutte le porte pubblicate nel file Compose fornito sono associate a ${ONECLI_BIND_HOST:-127.0.0.1}. Su un VPS, questo significa che la dashboard è in esecuzione, ma nessun client esterno può raggiungerla. Questo comportamento predefinito è corretto. Mantienilo e crea un tunnel:

ssh -N -L 10254:127.0.0.1:10254 you@your-server

Ora apri http://localhost:10254 sul laptop. Il traffico passa attraverso la connessione SSH, quindi la dashboard non viene esposta su Internet tramite una connessione non crittografata e non è necessario aprire altre porte nel firewall.

L'impostazione di ONECLI_BIND_HOST=0.0.0.0 pubblica la dashboard tramite HTTP non crittografato e pubblica anche PostgreSQL, usando la password predefinita del file Compose, onecli, se non imposti POSTGRES_PASSWORD. Inoltre pubblica l'accesso SSH sulla porta 10257, tramite un servizio che monta il socket Docker. Se più persone devono usare la dashboard, configura un reverse proxy con TLS (Transport Layer Security) davanti alla dashboard e lascia invariato l'host associato. Imposta ONECLI_EXTERNAL_URL sull'URL HTTPS e usa la configurazione del reverse proxy del progetto upstream, che inoltra i percorsi della dashboard, dell'API e del gateway ai rispettivi servizi. Un proxy, da solo, non impedisce l'accesso agli utenti non autorizzati. La documentazione sul self-hosting specifica che la registrazione è aperta per progettazione e che non esiste un'opzione per disabilitarla: chiunque raggiunga la dashboard può creare un account, al quale viene assegnata una propria organizzazione; per entrare nella tua organizzazione è invece necessario un invito. La documentazione consiglia di mantenere la dashboard dietro il perimetro della tua rete. Se il proxy pubblica già le altre applicazioni self-hosted, l'autenticazione inoltrata tramite un livello self-hosted di single sign-on colloca la dashboard dietro il sistema di accesso che il team utilizza già; in questo modo, rimuovere un utente da un solo punto chiude anche questo accesso.

Crea il primo account, quindi assegna una chiave modello

Apri la dashboard e crea subito il tuo account. Ogni nuovo account riceve una propria organizzazione e i collaboratori entrano nella tua tramite invito. Dopo la registrazione resta aperta, ed è un ulteriore motivo per tenere la dashboard dietro il tunnel o un proxy autenticato. Se stai eseguendo l'upgrade da una release precedente all'introduzione degli accessi, registrati subito: la documentazione per il self-hosting indica che i dati esistenti vengono assegnati al primo account che si registra. Su un host raggiungibile, quindi, vuoi che quell'account sia il tuo.

Quindi archivia una chiave modello prima di creare un agent. Un agent ospitato richiede una chiave modello assegnata e l'ordine è importante: archivia la chiave nella dashboard, assegnala all'agent e solo dopo avvia una conversazione. Se salti l'assegnazione, la sandbox non viene mai avviata; l'agent risponde nel thread spiegando che gli serve una chiave modello.

Limita le assegnazioni allo stretto necessario. Ogni agent riceve soltanto ciò che gli hai assegnato e il gateway applica questa regola a ogni richiesta. Di conseguenza, un agent che legge un repository non può accedere alla chiave del tuo provider di pagamenti. Lo stesso elenco di assegnazioni ti permette di controllare la spesa. Un agent personale che può chiamare qualsiasi modello di tua proprietà genera una fattura personale. Prima di crearne dieci, conviene quindi leggere come limitare quanto un agent può spendere per le chiamate ai modelli.

Come il gateway mantiene le chiavi fuori dagli agent

Il gateway è un proxy HTTPS scritto in Rust, in ascolto sulla porta 10255. Il client HTTP di un agent viene configurato per utilizzarlo e l'agent contiene una credenziale segnaposto invece di una credenziale reale. Il gateway confronta la richiesta in uscita con le autorizzazioni assegnate all'agent, decritta il secret reale, lo inserisce nella richiesta e la inoltra. I secret sono archiviati in PostgreSQL e cifrati con AES-256-GCM (advanced encryption standard, 256-bit, Galois/counter mode); vengono decrittati soltanto al momento della richiesta. Ogni chiamata viene registrata con l'identità dell'agent e la destinazione. Questo crea una traccia di audit che non è possibile ottenere quando le chiavi sono presenti nei profili shell di dieci persone.

Due aspetti determinano le modalità di distribuzione.

  • L'intercettazione HTTPS è un attacco man-in-the-middle. Il gateway genera una certificate authority locale, l'agent si fida di questa authority e il gateway termina la connessione TLS dell'agent, quindi ne apre una nuova verso il servizio upstream. Per questo motivo un agent il cui client HTTP non si fida della certificate authority del gateway restituisce un errore di verifica del certificato, non un errore di autenticazione.
  • L'agent si identifica con un header Proxy-Authorization. Su un singolo host, dove agent e gateway condividono una rete Docker interna, questo header non attraversa mai una rete che non controlli. Se configuri un agent esterno all'host per utilizzare il gateway, proteggi la connessione con una VPN o con un transport TLS, perché quell'header è un bearer token; upstream raccomanda una VPN per la porta del proxy CONNECT non cifrata.

Il compromesso reale è il seguente: per progettazione, il gateway legge in chiaro ogni richiesta effettuata dagli agent. È il processo più sensibile della macchina. Proteggi l'host di conseguenza e limita il numero di persone autorizzate ad accedere, usando utenti Linux con privilegi minimi.

Perché il runner non richiede una porta in ingresso

Il runner accetta solo connessioni in uscita. La documentazione specifica che «non espone porte raggiungibili dall'esterno, quindi funzionano laptop, homelab e VPC dietro NAT senza ingress, tunnel o gestione della terminazione TLS». NAT significa network address translation, il meccanismo usato dai router domestici. Il runner avvia la connessione verso il control plane e preleva da lì il lavoro; non c'è quindi nulla da inoltrare né da aprire.

Questa architettura è utile nella rete sandbox. Il file Compose definisce una seconda rete contrassegnata come internal: true, che in Docker significa nessuna connettività verso reti esterne. Le sandbox si collegano a questa rete. Il gateway è connesso a entrambe le reti, quindi rappresenta l'unica via di uscita. La documentazione del runner lo chiarisce: «una rete internal con il gateway connesso a entrambe le reti è ciò che rende l'uscita consentita solo tramite il gateway un confine effettivo, non una semplice indicazione». Un agent non può aggirare il gateway aprendo una connessione diretta verso un indirizzo esterno; è comunque la policy del gateway a decidere quali richieste autorizzare.

Verificalo sul tuo host, invece di fidarti del paragrafo precedente.

docker network ls
docker network inspect onecli-sandboxes | grep -i internal

Dovresti vedere "Internal": true. Se mostra false, il controllo dell'uscita è disattivato e il gateway torna a essere una semplice indicazione. Usa il nome della rete sandbox stampato da docker network ls, perché onecli-sandboxes è soltanto il valore predefinito.

Quanto è solida la sandbox di OneCLI?

Leggere lentamente questa sezione, perché nella descrizione del progetto il termine "sandboxed" ha un significato molto ampio, mentre il meccanismo è documentato nella documentazione del runner e nel codice del backend.

Il README afferma che ogni agente dispone di "una sandbox isolata, con un filesystem e una shell" e indica il Sandbox Supervisor come il componente che "viene eseguito all'interno di ogni sandbox e comunica tramite un'interfaccia harness indipendente dal vendor, in modo che il runtime dell'agente possa essere sostituito". Nessuna delle due frasi specifica in cosa consista l'isolamento. La documentazione del runner lo chiarisce: il backend predefinito è Docker (RUNNER_BACKEND=docker) e una sandbox è un container Docker con un limite di memoria, un limite CPU e un limite al numero di processi, collegato alla rete interna. Il codice prevede un punto di estensione per altri backend. Il codice attuale del runner implementa anche un backend Kubernetes, usato dall'Helm chart per i Job delle sandbox e per i volumi persistenti. Nell'installazione Compose descritta in questa guida, una sandbox è un container Docker.

La documentazione del runner descrive ora il confine Docker: l'agente viene eseguito come node, con no-new-privileges, tutte le capacità Linux rimosse e il profilo seccomp predefinito di Docker. Il backend monta nella sandbox soltanto la home persistente dell'agente. È quindi opportuno adottare un'interpretazione restrittiva. I limiti sono limiti delle risorse. La rete interna è un vero controllo sull'uscita del traffico. L'isolamento tra un agente e l'host usa questi controlli dei container, ma un container condivide il kernel dell'host.

Va considerato anche un secondo fatto. Il servizio runner monta /var/run/docker.sock, perché è così che crea le sandbox. L'accesso al socket di un Docker daemon eseguito con privilegi root equivale all'accesso root sull'host: chiunque possa chiamare quell'API può avviare un container con il filesystem dell'host montato al suo interno. Il runner fornito usa quel socket per il backend Docker. Di conseguenza, il processo runner è sensibile quanto il gateway. Anche il terminatore SSH monta lo stesso socket per poter eseguire comandi nei container delle sandbox, e i commenti del file Compose indicano che questo mount equivale all'accesso root sull'host. Mantieni quindi la porta 10257 in ascolto solo su loopback, salvo che tu abbia un motivo per esporla.

Considera con prudenza il confine basato sul kernel condiviso. In pratica, questo significa adottare tre abitudini.

  1. Esegui OneCLI su una macchina che non svolga altre funzioni. Non usarla per servizi di produzione non correlati, database condivisi o dati di altri team.
  2. Presupponi che un agente che ottenga l'esecuzione di codice arbitrario all'interno della propria sandbox possa raggiungere l'host, e fai in modo che questo evento sia gestibile mantenendo i backup fuori dalla macchina.
  3. Leggi apps/runner/src oppure chiedi conferma al team upstream prima di dire a un collega che l'agente è contenuto.

Per vedere come si presenta un confine documentato e quali domande porre al team upstream, confronta queste informazioni con come si presenta un vero confine di sandbox per un agente. La domanda è se il meccanismo documentato copra le minacce che devi impedire.

La separazione delle licenze e perché verificarla prima di procedere

Il core di OneCLI è distribuito con licenza Apache-2.0 e il self-hosting in produzione è consentito. Le directory denominate ee/ sono soggette a una licenza OneCLI Enterprise separata: sono gratuite per sviluppo, test e valutazione, mentre per l'uso in produzione è necessario un abbonamento. Le note di rilascio della versione v2.0.1 del 18 agosto 2026 indicano il ripristino di un file di licenza Apache-2.0 rilevabile da GitHub, quindi il badge nella pagina del repository è cambiato di recente. Verifica il tag che distribuisci effettivamente, invece di basarti su un riepilogo scritto in un'altra data.

cd onecli && find . -type d -name ee -not -path '*/node_modules/*'

Tutto ciò che si trova in quei percorsi appartiene alla parte commerciale. Se una funzionalità da cui prevedi di dipendere si trova in quelle directory, verifica prima il costo, prima di costruirvi un processo operativo.

Aggiornamenti, migrazioni e l'unico file che non puoi perdere

Gli aggiornamenti devono aggiornare le immagini dei servizi e l'immagine separata dell'agent, quindi riavviare i sandbox in esecuzione. Un servizio di migrazione eseguito una sola volta viene avviato prima dell'API a ogni up. Se una migrazione fallisce, lo stack non si avvia invece di fornire il servizio con uno schema migrato solo parzialmente. È il comportamento desiderato, perché un aggiornamento non riuscito si manifesta come un'interruzione del servizio anziché come una corruzione silenziosa, come spiega docker compose logs migrations.

Un passaggio è facile da trascurare. La documentazione per l'hosting autonomo sconsiglia di eseguire l'aggiornamento con un semplice docker compose pull && docker compose up -d, perché l'immagine del sandbox dell'agent non è un servizio Compose. È il valore RUNNER_AGENT_IMAGE sul runner, quindi docker compose pull non lo rileva e gli agent ospitati possono continuare a usare una vecchia immagine del sandbox senza alcun avviso. Aggiorna il checkout, modifica il pin ed esegui lo strumento di aggiornamento documentato: scarica l'immagine del sandbox e riavvia i sandbox in esecuzione.

cd onecli
git pull
sed -i 's/^ONECLI_VERSION=.*/ONECLI_VERSION=2.17.0/' docker/.env
pnpm install
pnpm run setup --upgrade
cd docker
docker compose logs migrations

Sostituisci 2.17.0 con la release a cui stai passando. Il riavvio dei sandbox interrompe il lavoro in corso, ma lo spazio di lavoro persistente di ogni agent viene conservato.

Se invece hai eseguito l'installazione con lo script di installazione, esegui nuovamente quello script anziché scaricare le immagini manualmente, così il file Compose resta allineato alle immagini a cui fa riferimento. Esporta prima ONECLI_VERSION se vuoi una release specifica, perché lo script sovrascrive un pin conservato soltanto nel relativo file .env.

Esegui il backup del database, della configurazione e dei volumi dello spazio di lavoro degli agent. PostgreSQL contiene gli agent, le conversazioni, la memoria e i secret crittografati. Il file docker/.env contiene SECRET_ENCRYPTION_KEY. Senza questa chiave, i secret crittografati non sono leggibili, anche se il resto del database viene ripristinato. Lo /workspace di ogni agent risiede in un volume persistente separato e richiede un backup dedicato.

cd onecli/docker
docker compose exec -T postgres pg_dump -U onecli onecli | gzip > ~/onecli-db.sql.gz
install -m 600 .env ~/onecli-env.backup

Conserva queste copie e i backup degli spazi di lavoro fuori dal server. La procedura è la stessa richiesta da qualsiasi stack Compose con stato. Se già esegui il backup e l'aggiornamento di uno stack Docker Compose con una pianificazione, aggiungi i volumi del database, della configurazione e degli spazi di lavoro, quindi non devi più occupartene.

Quando non funziona

  • Lo stack non raggiunge mai lo stato healthy e docker compose up -d --wait termina con un codice diverso da zero. Leggere prima docker compose logs migrations, perché l’API attende deliberatamente quel servizio.
  • Un agent resta inattivo e non compare alcun sandbox. Verificare che COMPOSE_PROFILES=runner sia in docker/.env e che docker compose ps elenchi un runner. Controllare quindi che all’agent sia stata assegnata una model key valida, perché i sandbox non vengono avviati senza una chiave.
  • Non sono rimasti slot disponibili. RUNNER_MAX_SANDBOXES usa 4 come valore predefinito e un sandbox con un processo in background attivo mantiene occupato il proprio slot finché il limite di permanenza in esecuzione non lo elimina. docker ps mostra quali processi sono realmente attivi.
  • Lo stack non si avvia e Docker segnala che una porta è già in uso. Con il profilo runner attivo, il punto di accesso SSH richiede 10257 oltre alle altre quattro porte.
  • I container scompaiono oppure l’host rallenta drasticamente. Verificare l’esaurimento della memoria con dmesg -T | grep -i oom; il limite di memoria predefinito consente a un singolo sandbox di usare fino a 2048 MB.
  • Le chiamate HTTPS di un agent falliscono con errori di verifica del certificato anziché con errori di autenticazione. Il relativo client HTTP non considera attendibile l’autorità di certificazione del gateway.
  • Dopo l’eliminazione di un agent restano container o volumi obsoleti. Il runner esegue la riconciliazione ogni 60 secondi ed elimina gli orfani più vecchi di RUNNER_ORPHAN_GRACE_SECONDS, il cui valore predefinito è 3600; attendere quindi un’ora prima di considerarlo una perdita.

È la soluzione giusta per te?

La verifica di adeguatezza è breve. OneCLI è adatto quando più persone hanno bisogno di un agent e vuoi gestire le credenziali in un unico punto: un solo archivio da ruotare, un unico audit log da consultare e un'unica dashboard in cui la revoca dell'accesso di una persona abbia effetto reale. Questo è un problema operativo concreto, e copiare una API key su sei laptop è una soluzione ancora peggiore.

Per una sola persona è un insieme di componenti eccessivo, senza vantaggi reali. Dovresti eseguire PostgreSQL, un control plane, un gateway e un runner per ottenere un unico agent; inoltre, il problema delle credenziali che il gateway risolve è quasi inesistente quando l'unica persona che possiede la chiave sei tu. Usa invece un singolo harness su una macchina più piccola: un harness per un singolo agent su un VPS svolge lo stesso lavoro con una frazione della memoria. Se non hai ancora scelto una direzione, la panoramica confronto tra agent AI self-hosted è il primo passo più economico. Se la parte che non conosci sono gli agent, non i server su cui vengono eseguiti, segui prima un percorso graduale per capire come funzionano davvero gli agent, perché sapere che cosa fanno realmente una chiamata a uno strumento e un archivio della memoria permette di stabilire quali autorizzazioni assegnare all'agent di ciascuna persona.

FAQ

Quali sono i requisiti minimi del server per eseguire OneCLI in self-hosting?

Docker con il plugin Compose versione 2.24.0 o successiva, Node.js e pnpm per la procedura guidata di configurazione usata qui, oltre a memoria sufficiente. PostgreSQL è incluso nel file Compose, quindi non è necessario installarlo separatamente. La memoria determina il dimensionamento: per impostazione predefinita, il runner limita ogni sandbox dell'agente a 2048 MB e la relativa documentazione richiede circa 10 GiB liberi oltre allo stack di base per gestire il limite predefinito di quattro sandbox. In base al budget di 2 GB per lo stack di base assunto nel grafico, un server da 4 GB consente una sandbox al limite massimo, mentre un server da 16 GB copre il limite predefinito di concorrenza. Sono valori utili per la pianificazione, non requisiti minimi misurati né allocazioni di memoria fisse.

OneCLI richiede PostgreSQL o può usare SQLite?

Richiede PostgreSQL. DATABASE_URL è documentata come stringa di connessione PostgreSQL, il file Compose fornito esegue postgres:18-alpine con un volume pgdata e un servizio separato per le migrazioni applica lo schema prima dell'avvio dell'API. Non è documentata alcuna opzione SQLite. Per usare un server PostgreSQL esterno, configura sia il servizio API sia il servizio per le migrazioni in modo che lo utilizzino; il file Compose fornito imposta le relative stringhe di connessione sul servizio PostgreSQL incluso.

La sandbox dell'agente OneCLI costituisce un vero confine di sicurezza?

Il meccanismo Compose documentato consiste in un container Docker con limiti di memoria, CPU e processi, collegato a una rete contrassegnata come internal: true, in modo che il traffico esterno passi dal gateway. Il controllo del traffico in uscita è effettivo e puoi verificarlo con docker network inspect. L'agente viene eseguito come node, con no-new-privileges, tutte le funzionalità Linux rimosse e il profilo seccomp predefinito di Docker, ma con il kernel dell'host condiviso. Il runner e il terminatore SSH montano entrambi /var/run/docker.sock, equivalente all'accesso root su un host che usa un demone Docker rootful. Esegui OneCLI su un server dedicato e conserva i backup al di fuori di quel server.

È necessario aprire porte in ingresso per OneCLI?

No. Il runner consente solo connessioni in uscita e non espone porte raggiungibili dall'esterno, quindi funziona dietro NAT senza tunnel. Per impostazione predefinita, il file Compose associa il dashboard, il gateway, l'API, PostgreSQL e, con il profilo runner, il punto di accesso SSH sulla porta 10257 a 127.0.0.1. Puoi raggiungere il dashboard tramite un tunnel SSH oppure usare la configurazione reverse proxy upstream con TLS e le route richieste per dashboard, API e gateway se devono accedervi più persone. Tieni presente che la registrazione resta aperta a chiunque possa raggiungerla. Il gateway sulla porta 10255 è destinato agli agenti e, su un singolo server, tali agenti lo raggiungono tramite la rete Docker interna.

OneCLI è gratuito per l'uso all'interno di un'azienda?

Il core è distribuito con licenza Apache-2.0 e l'uso self-hosted in produzione è consentito senza una licenza commerciale. Le directory denominate ee/ sono coperte dalla OneCLI Enterprise License, gratuita per sviluppo, test e valutazione, ma soggetta a sottoscrizione in produzione. La suddivisione cambia tra le release e le note della v2.0.1 del 18 August 2026 menzionano il ripristino di un file di licenza Apache-2.0 rilevabile da GitHub. Prima di basare un workflow su una singola funzionalità, verifica quindi LICENSE e le directory ee/ nel tag esatto che intendi distribuire.

Questo articolo ti è stato utile?