Come usare Omnigent per gestire più agenti CLI

Cos'è Omnigent

Omnigent è un meta-harness open source: un livello di orchestrazione che gestisce gli strumenti a riga di comando (CLI) per agenti già installati sul sistema. Non sostituisce Claude Code, Codex, Cursor, OpenCode, Hermes o Pi. Si occupa di avviarli, assegnare a ciascuno un compito e supervisionare il risultato all'interno di una singola sessione con un unico set di policy. Databricks ha pubblicato il repository nel giugno 2026 sotto licenza Apache 2.0 e la pagina principale riporta ancora Status: alpha.

L'obiettivo pratico è circoscritto e vale la pena esporlo chiaramente. Si descrive un agente una sola volta, in formato YAML, specificando l'harness che deve eseguirlo. Modificando quella singola riga, lo stesso agente viene eseguito sulla CLI di un fornitore diverso. Nient'altro nella configurazione cambia, poiché Omnigent gestisce il ciclo al di sopra degli agenti, anziché il ciclo al loro interno.

Cos'è un meta-harness e in che modo differisce da un framework?

Un harness è il programma che racchiude un modello in un ciclo. Legge il prompt, richiama strumenti, modifica file e fornisce un riscontro. Claude Code è un harness. Codex è un harness. Si installa, si effettua l'accesso e funziona autonomamente.

Un framework è una libreria su cui si scrive codice. Si importa, si definiscono i passaggi in Python e il proprio programma diventa l'agente. Cambiare fornitore in questo caso significa modificare il codice, poiché il client del fornitore è integrato nel programma.

Un meta-harness si colloca un livello sopra entrambi. È un supervisore che esegue gli harness come processi figli. Omnigent avvia la CLI del fornitore, gli assegna il lavoro e legge i risultati. Si mantiene la CLI già installata e si conserva qualsiasi abbonamento o chiave API (application programming interface) già attiva. Questa è l'intera differenza, e determina a chi è rivolto lo strumento: a persone che hanno già diversi agenti CLI operativi e sono stanche di gestirli un terminale alla volta.

Quale problema risolve un livello di orchestrazione?

• Costi di migrazione tra vendor ridotti. La definizione dell'agente contiene harness e model come dati, pertanto spostare un ruolo da un vendor all'altro richiede solo una modifica al file YAML, non una riscrittura.
• La revisione può coinvolgere vendor diversi. Un diff scritto da un modello viene letto da un modello di un'azienda diversa. Due modelli della stessa famiglia tendono a condividere i medesimi punti ciechi, quindi un secondo parere proveniente dallo stesso vendor ha un valore inferiore.
• La policy ha un'unica sede. I limiti di spesa e le richieste di approvazione sono dichiarati nel file dell'agente e si applicano a ogni sotto-agente sottostante.
• La sessione sopravvive a qualsiasi singolo strumento. Una singola trascrizione copre il lavoro svolto da diverse CLI, permettendo di rileggere quanto accaduto senza dover ricomporre quattro diversi log di terminale.

Il costo è rappresentato dal livello stesso. Ogni bug in Omnigent diventa un bug che si interpone tra l'utente e un agente che in precedenza funzionava autonomamente. In fase alpha questo è un costo reale, non teorico.

Dove si colloca un sistema multi-agente rispetto agli strumenti a singolo agente

Se non hai ancora eseguito un agente su un server, inizia da lì. La nostra guida su come eseguire un agente di programmazione su una VPS copre interamente il caso del singolo agente, ed è la configurazione che Omnigent presuppone tu abbia già. Il campo più ampio degli agenti AI self-hosted è il luogo in cui scegliere gli agenti stessi, mentre imparare come funzionano realmente gli agenti è il punto di partenza migliore se il vocabolario utilizzato qui è nuovo per te.

Omnigent opera inoltre su un asse differente rispetto a un livello di connessione. Attività come fornire agli agenti l'accesso alle proprie fonti di dati riguardano ciò che un agente può raggiungere. Omnigent riguarda invece quale agente viene eseguito, in quale ordine e entro quali limiti. Puoi aver bisogno di entrambi contemporaneamente, poiché non si sovrappongono.

Requisiti preliminari per l'installazione

• Python 3.12 o versione successiva. Il pacchetto pubblicato dichiara requires-python >= 3.12.
• tmux, poiché i terminal harness vengono eseguiti al suo interno.
• Almeno una CLI di un vendor, già installata e con autenticazione effettuata.
• Node.js 22 solo se si esegue la compilazione da un checkout git. Il wheel su PyPI contiene già gli asset web compilati, pertanto l'installazione standard non richiede Node.

Installare una release bloccata, non la versione main

curl -fsSL https://raw.githubusercontent.com/omnigent-ai/omnigent/main/scripts/install_oss.sh | sh -s -- --version 0.7.0

La parte sh -s -- non è un elemento decorativo. Senza di essa, sh interpreta --version come una propria opzione e l'installer non riceve mai il flag; di conseguenza, si ottiene sempre la versione più recente disponibile. In un repository che rilascia modifiche incompatibili ogni poche settimane, questa è la differenza tra un sistema riproducibile e un imprevisto.

L'installer utilizza uv, il gestore di pacchetti Python di Astral, e propone di installare uv per primo se non è presente. Se uv è già installato, è possibile saltare lo script:

uv tool install --force --python 3.12 "omnigent==0.7.0"

Gli extra seguono lo stesso schema e il flag va ripetuto: --extra e2b --extra kubernetes sullo script, oppure "omnigent[e2b,kubernetes]" con uv. Si noti che il tag git è v0.7.0, mentre la versione del pacchetto su PyPI è 0.7.0.

uv inserisce il binario nella directory indicata da uv tool dir --bin, solitamente ~/.local/bin, e l'installer propone di aggiungerla al profilo della shell. Se il comando non viene trovato subito dopo un'installazione pulita, il motivo è questo. Verificare cosa è stato installato:

omni upgrade --check

Questo comando confronta la versione installata con l'ultima pubblicata e indica se è disponibile un aggiornamento, senza eseguirlo. omni e omnigent sono lo stesso programma con due nomi diversi.

Configurazione del provider del modello

omni setup

La procedura guidata rileva le credenziali già presenti nell'ambiente e richiede quelle mancanti. Gestisce chiavi API, abbonamenti ai vendor, gateway come OpenRouter o Ollama e workspace Databricks. Se è già in esecuzione un server di modelli locale con Ollama sulla stessa macchina, è possibile puntare un gateway verso di esso: in questo modo il traffico non lascerà mai il server.

Esecuzione multi-agente minima

Gli agenti di esempio si trovano nel repository, quindi clona lo stesso tag che hai installato invece di main.

git clone --depth 1 --branch v0.7.0 https://github.com/omnigent-ai/omnigent.git
cd omnigent
omnigent run examples/polly/

Polly è l'orchestratore di programmazione multi-agente distribuito con il repository. La sua configurazione dichiara sotto-agenti denominati claude_code, codex, opencode, cursor, hermes e pi, e una regola che rende utile l'intero esercizio: la revisione viene sempre eseguita da un fornitore diverso rispetto a chi ha implementato il codice. Polly non scrive codice in autonomia. Pianifica, suddivide l'obiettivo in attività, delega ciascuna di esse e instrada ogni diff a un revisore di un altro fornitore.

Prima di delegare qualsiasi operazione, Polly esegue un controllo preliminare per verificare quali CLI dei sotto-agenti esistano effettivamente sulla macchina. Con una sola CLI di un fornitore installata non c'è nessuno a cui passare il diff, quindi installane almeno due prima di valutare l'output. Debby, l'altro esempio fornito, è un agente di dibattito con due teste, una Claude e una GPT:

omni debby

È un modo rapido per confermare che due provider siano configurati, poiché necessita di entrambi per produrre qualsiasi output.

I sub-agent sono dichiarati come tool

Il file dell'agente è in formato YAML. executor definisce l'harness, il modello e l'autenticazione. tools contiene i server MCP (model context protocol), le funzioni Python e i sub-agent. Un sub-agent è un tool dotato di type: agent e di un proprio executor, che costituisce il meccanismo alla base di quanto descritto sopra.

name: orchestrator
prompt: |
  You coordinate coding and review tasks.

executor:
  harness: claude-sdk
  model: databricks-claude-sonnet-4-6

tools:
  coder:
    type: agent
    prompt: Write and test code.
    executor:
      harness: claude-sdk
      model: databricks-claude-opus-4-7
  reviewer:
    type: agent
    prompt: Review proposed changes.
    executor:
      harness: claude-sdk
      model: databricks-claude-sonnet-4-6

omnigent run path/to/my_agent.yaml

Questi ID di modello provengono dall'esempio docs/AGENT_YAML_SPEC.md del progetto e sono nomi ospitati su Databricks. Sostituisci harness e model con i valori configurati sulla tua macchina in omni setup. Altri valori dell'harness presenti nelle specifiche includono antigravity, copilot, kimi, qwen e acp:<slug> per qualsiasi elemento che utilizzi il protocollo generico. Le specifiche supportano anche pass_history: true su un sub-agent, che gli trasmette la conversazione del genitore. Questa operazione consuma token a ogni delega, pertanto è consigliabile disattivarla per i sub-agent che necessitano solo del task assegnato.

Perché l'orchestrazione a lunga esecuzione richiede una VPS

Un'esecuzione multi-agente non è un comando da due minuti. Richiede pianificazione, delega, attesa su worktree git paralleli, revisione e correzione. Chiudere il coperchio del portatile interrompe tutto. Una VPS (virtual private server) rimane attiva e mantiene la sua rete, quindi la sessione sopravvive anche quando non la stai monitorando.

omnigent server --background
omnigent server status

Il server ospita un'interfaccia web sulla porta 6767. omnigent server status segnala se un'istanza è in esecuzione, mentre omnigent stop la arresta. Nelle release precedenti alla v0.7.0 si utilizzava omni server start, comando rimosso, pertanto le guide e gli screenshot meno recenti non corrisponderanno a ciò che vedi nel terminale.

Non pubblicare la porta 6767 su un indirizzo pubblico. Due configurazioni sono sicure. Mantieni la porta chiusa nel firewall ed effettua il forwarding tramite SSH con ssh -N -L 6767:localhost:6767 you@your-server, quindi apri l'interfaccia web all'indirizzo http://localhost:6767 sulla tua macchina locale. In alternativa, termina il TLS (transport layer security) davanti al servizio e abilita l'autenticazione:

OMNIGENT_AUTH_ENABLED=1 omnigent server --background

La parte relativa al firewall è un'operazione standard, descritta in le basi del firewall ufw per una VPS, e se il server esegue già dei container dietro Traefik davanti a diverse app Docker Compose, allora Omnigent è semplicemente un ulteriore servizio che segue lo stesso schema.

Per un deploy tramite container, la directory deploy/ del repository contiene una configurazione Compose: ./bootstrap.sh genera i secret in .env, quindi docker compose up -d avvia Omnigent e Postgres sulla porta 6767. DATABASE_URL seleziona Postgres o SQLite, e OMNIGENT_AUTH_ENABLED imposta come predefinito 1 all'interno dei container, che è l'impostazione corretta per qualsiasi servizio raggiungibile dall'esterno.

Per quanto riguarda il dimensionamento, le note di deploy indicano che il working set del server è di circa 512 MB - 1 GB, e la configurazione Fly.io assegna 1 GB. Questa cifra si riferisce al solo supervisore. Ogni sotto-agente è un processo separato che mantiene il proprio checkout e il proprio client per il modello, quindi dimensiona il server in base al numero di agenti. Una volta che il server è attivo, omnigent login https://your-host seguito da omnigent host https://your-host registra il tuo portatile, e omnigent attach <session_id> riprende una sessione attiva da un altro dispositivo.

Isolare ogni sub-agent in una sandbox prima di terminare la configurazione

Omnigent distribuisce una sandbox a livello di sistema operativo chiamata Omnibox. Su Linux utilizza i namespace di bubblewrap e seccomp, in modo che sia il kernel a imporre il limite e non il prompt dell'agente. Un agente vittima di prompt injection non può aggirare una regola del kernel. Installare prima la dipendenza:

sudo apt install bubblewrap

La configurazione risiede sotto os_env nel file dell'agente:

os_env:
  type: caller_process
  cwd: .
  sandbox:
    type: linux_bwrap
    write_paths: [.]
    write_files: []
    read_paths: []
    allow_network: true
    cwd_allow_hidden: [.venv]
    env_passthrough: []
    egress_rules: []
    credential_proxy: []

La directory di lavoro è in sola lettura finché non viene elencata in write_paths, quindi un agente che subisce un malfunzionamento non può scrivere al di fuori del workspace. I dotfile restano nascosti a meno che non siano specificati in cwd_allow_hidden; ciò significa che un permesso di lettura esteso non espone silenziosamente .ssh o .aws. Impostare egress_rules per far transitare tutto il traffico HTTP e HTTPS attraverso un proxy con policy di negazione predefinita, scrivendo ogni regola come "METHODS host/path-glob". credential_proxy compie un ulteriore passo: l'agente detiene solo un segnaposto e il proxy sostituisce il secret reale nel momento in cui la richiesta esce; in questo modo, una trascrizione trafugata non rivela nulla di utilizzabile. In una configurazione multi-harness, ogni sub-agent trasporta il proprio blocco sandbox nel rispettivo file di configurazione sotto agents/, permettendo di negare l'accesso alla rete al revisore pur mantenendolo per l'implementatore.

Il limite è indicato nella documentazione ed è rilevante. La sandbox del sistema operativo si applica alle chiamate agli strumenti sys_os_* e ai terminali. Non copre i server MCP, né il processo supervisor di Omnigent stesso. Un server MCP avviato viene eseguito al di fuori della sandbox con i privilegi dell'utente. Questa lacuna spiega perché il pattern più solido rimanga l'uso di una macchina usa e getta per ogni agente, argomento trattato in esecuzione di agenti di programmazione in una VM temporanea. L'altra metà del lavoro riguarda le credenziali, e mantenere i secret fuori dalla portata di un agente diventa più complesso, non più semplice, quando sei sub-agent condividono lo stesso host.

I limiti di spesa sono policy dichiarate nello stesso file:

policies:
  budget:
    type: function
    handler: omnigent.policies.builtins.cost.cost_budget
    factory_params:
      max_cost_usd: 5.00
      ask_thresholds_usd: [1.00, 3.00]

Un'esecuzione che pianifica con un fornitore, implementa con un secondo e revisiona con un terzo sta generando costi in tre punti contemporaneamente; impostare quindi il tetto massimo prima della prima esecuzione non presidiata, anziché dopo la prima fattura. Le funzioni integrate includono anche max_tool_calls_per_session e ask_on_os_tools, che richiedono l'approvazione prima di operazioni su file e shell. Le nostre note su mantenere sotto controllo i costi degli agenti AI su una VPS si applicano direttamente qui, con maggiore rigore, poiché i sub-agent in parallelo moltiplicano il tasso di consumo delle risorse.

Qual è la velocità di aggiornamento di questo repository?

[
  {
    "version": "v0.2.0",
    "released": "2026-06-19",
    "interval": 3
  },
  {
    "version": "v0.3.0",
    "released": "2026-06-27",
    "interval": 8
  },
  {
    "version": "v0.4.0",
    "released": "2026-07-03",
    "interval": 6
  },
  {
    "version": "v0.5.0",
    "released": "2026-07-10",
    "interval": 7
  },
  {
    "version": "v0.5.1",
    "released": "2026-07-10",
    "interval": 0
  },
  {
    "version": "v0.6.0",
    "released": "2026-07-21",
    "interval": 11
  },
  {
    "version": "v0.7.0",
    "released": "2026-07-27",
    "interval": 6
  }
]

Queste sono le date di rilascio pubblicate sulla pagina dei software rilasciati dal progetto, consultata il 3 agosto 2026. 7 release con tag sono state pubblicate tra il 2026-06-19 e il 2026-07-27, e l'intervallo più lungo tra due rilasci è stato di 11 giorni. La versione v0.5.1 è stata rilasciata lo stesso giorno della precedente. Il primo rilascio, 0.1.1 del 16 giugno 2026, è escluso dal grafico poiché non esiste un tag precedente da cui calcolare l'intervallo.

Due di questi rilasci hanno reso incompatibili comandi già documentati nelle guide. La v0.7.0 ha rimosso omni server start in favore di omni server --background. La v0.6.0 ha rinominato l'extra omnigent[memory] in omnigent[hindsight], pertanto una riga di installazione copiata da una guida di giugno fallisce su una build di luglio. Questo è il motivo per cui usare --version nel comando di installazione e specificare un tag nel proprio git clone non è una questione di stile, ma una necessità tecnica.

Cosa non affiderei ancora a questo strumento

Ad agosto 2026 il repository conta circa 8,1k stelle, 1,2k fork e all'incirca 350 issue aperte, con una prima release pubblica risalente a sette settimane fa. Le stelle misurano l'interesse, e l'interesse non è sinonimo di maturità. Il progetto si definisce alpha, e la cronologia delle release sopra riportata conferma che si tratta effettivamente di uno stato alpha.

• Non lo eseguirei su un host che contiene credenziali di produzione, poiché la sandbox non copre i server MCP o il supervisore.
• Non lascerei un'esecuzione incustodita senza una policy cost_budget, poiché tre vendor possono fatturare in parallelo e non esiste altro meccanismo per bloccarli.
• Non esporrei il server su un indirizzo IP pubblico senza aver impostato OMNIGENT_AUTH_ENABLED e senza un layer TLS davanti.
• Non considererei il file YAML dell'agente come stabile tra le versioni minor, quindi è necessario bloccare la versione e leggere le note di rilascio prima di eseguire l'aggiornamento.

Un'ultima cosa da sapere prima che possa sorprenderti: la v0.6.0 ha introdotto la telemetria di utilizzo anonimizzata, e il progetto la documenta in una pagina dedicata alla telemetria. Leggi quella pagina e prendi una decisione consapevole se la macchina gestisce lavoro per conto di clienti.

Ciò in cui Omnigent è realmente valido oggi è lo scopo per cui è stato costruito. Hai tre o quattro CLI di agenti, le paghi già e vuoi che una di esse scriva mentre un'altra revisiona. Questo funziona ora, su una singola macchina, con un vero sandboxing su Linux. Considera tutto ciò che va oltre questo ambito come promettente ma non ancora completato.

FAQ

Omnigent è un agente o un sistema che esegue agenti?

Esegue agenti. Omnigent è un meta-harness: avvia le CLI dei vendor che hai già installato, come Claude Code, Codex o OpenCode, assegna a ciascuno un compito e supervisiona i risultati in un'unica sessione. Non include alcun modello proprio. Per questo motivo differisce da un framework, in cui scrivi codice Python basato su una libreria e il tuo programma diventa l'agente.

Devo avere Claude Code e Codex installati affinché Omnigent sia utile?

È necessario avere almeno una CLI di un vendor installata e configurata, poiché Omnigent pilota tali programmi invece di sostituirli. Per l'esempio Polly fornito, sono necessari due o più vendor diversi. La regola di Polly prevede che la revisione sia sempre eseguita da un vendor diverso da quello che ha implementato il codice; pertanto, con una sola CLI presente, non c'è un secondo vendor a cui inviare il diff.

Come posso installare una versione specifica di Omnigent invece dell'ultima?

Passa --version allo script di installazione tramite sh -s --, come in sh -s -- --version 0.7.0. Senza -s --, il flag viene consumato da sh stesso e lo script installa la release più recente. Se uv è già presente, uv tool install --force --python 3.12 "omnigent==0.7.0" svolge la stessa funzione. Il tag git è v0.7.0, mentre la stringa di versione PyPI è 0.7.0.

La sandbox Omnibox è sufficiente per eseguire agenti senza supervisione?

È robusta per ciò che copre ed è chiara riguardo ai suoi limiti. Su Linux utilizza bubblewrap e seccomp, quindi il kernel impone limiti su file e rete che l'agente non può ignorare. La documentazione specifica che si applica alle chiamate agli strumenti sys_os_* e ai terminali, e che non copre i server MCP o il processo di supervisione di Omnigent. Un server MCP viene quindi eseguito con i tuoi permessi standard; per questo motivo, una macchina virtuale usa e getta per ogni agente rimane la soluzione di isolamento più sicura per il lavoro senza supervisione.

Quanta memoria richiede un server Omnigent su una VPS?

Le note di deploy del progetto indicano per il server un working set di circa 512 MB - 1 GB, e la sua configurazione Fly.io assegna 1 GB. Questo copre solo il supervisore e l'interfaccia web sulla porta 6767. Ogni sotto-agente è un processo separato con la propria copia di lavoro e il proprio client per il modello; inoltre, le esecuzioni in stile Polly utilizzano git worktree paralleli. Pertanto, dimensiona RAM e disco in base al numero di agenti che prevedi di eseguire contemporaneamente, piuttosto che in base al solo server.