Installare Agentlas OS 1.2.0 su un VPS Linux

Che cos’è effettivamente Agentlas OS

Agentlas OS è un runtime open source per agenti che conserva gli agenti specializzati su disco come pacchetti e crea un orchestratore temporaneo per ogni attività. Puoi eseguirlo sul tuo server installandolo nell’account utente che utilizzi su un VPS Linux. Non è un servizio. Non include un daemon, non resta in ascolto su alcuna porta, non ha un’interfaccia web e nel repository non è presente alcuna immagine container.

Questa caratteristica determina tutto il resto di questa pagina. La maggior parte dei sistemi multi-agente esegue un processo supervisore persistente che mantiene gli agenti. Agentlas adotta l’approccio opposto: gli specialisti sono file memorizzati su disco e l’orchestratore esiste soltanto durante l’esecuzione di un’attività. In pratica, un hub inattivo consuma spazio su disco, non memoria.

Il progetto chiama il proprio core open source Hephaestus. Questo è il nome che troverai nei comandi, nei percorsi e nelle variabili d’ambiente. Il repository è agentlas-ai/Agentlas-OS, distribuito con licenza Apache-2.0 e scritto principalmente in Python.

Quanto è maturo questo progetto, in pratica

Il repository è stato creato il 4 giugno 2026. Al 12 agosto 2026 ha circa dieci settimane di vita, con circa 1.150 stelle e 112 fork. Per uno strumento a cui affidare attività reali, è ancora giovane.

La frequenza dei rilasci è più importante dell'età. La versione v1.1.103 è stata pubblicata l'8 agosto 2026 e la v1.2.0 il 12 agosto 2026. Nella serie 1.1 sono stati pubblicati oltre cento rilasci contrassegnati, alcuni giorni anche più di uno, tramite automazione. Un progetto che procede a questa velocità può modificare il proprio comportamento tra martedì e giovedì.

Quindi fissa la versione del rilascio. L'installer legge una variabile d'ambiente per questo scopo e tutta la guida seguente la utilizza. Un'installazione senza versione fissa di un progetto che pubblica rilasci più volte al giorno installa qualunque versione si trovi su main in quel momento.

Cosa serve sul VPS

I requisiti sono ridotti, perché non viene eseguito nulla in background.

• Un VPS Linux. Ubuntu 24.04 è una buona base. L'installer rileva il sistema operativo con uname -s e, su Linux, segue il ramo non-macOS; è quindi supportato anche un server headless.
• curl, tar e git sul server, oltre a un interprete Python funzionante.
• Accesso HTTPS in uscita verso raw.githubusercontent.com e github.com. L'installer scarica un archivio di release e ne verifica l'hash SHA-256; un server senza connettività in uscita non può quindi eseguire l'installazione.
• Un host harness, cioè l'agente di programmazione che comunica direttamente con un modello. Claude Code, Codex, opencode, goose e Hermes sono tutti supportati come adapter.

Non serve l'account root. L'installer scrive soltanto nella directory home dell'utente e in ~/.local/bin e, se un percorso non è scrivibile, mostra un avviso invece di interrompersi. Se devi ancora scegliere il server, eseguire un agente di programmazione su un VPS descrive la configurazione dell'immagine di base e dell'accesso, su cui si basa questa procedura.

Installare la release fissata

Il README upstream documenta una singola riga che esegue il pipe di uno script da main direttamente in bash. Scaricalo e leggilo prima. Scrive nella configurazione della shell e in ogni harness degli agenti che trova, quindi vale la pena dedicargli dieci secondi.

curl -fsSL -o install-all-runtimes.sh \
  https://raw.githubusercontent.com/agentlas-ai/Agentlas-OS/main/scripts/install-all-runtimes.sh
less install-all-runtimes.sh
HEPHAESTUS_REF=v1.2.0 bash install-all-runtimes.sh

HEPHAESTUS_REF è il pin. All’interno dello script la riga è version="${HEPHAESTUS_REF:-v1.2.0}", quindi, se non lo imposti, oggi ottieni v1.2.0 e la prossima settimana potresti ottenere altro. Impostalo esplicitamente: la ricompilazione di ottobre installerà ciò che hai testato ad agosto.

Un limite da tenere presente: l’URL dello script sopra segue main, mentre HEPHAESTUS_REF fissa il payload del runtime scaricato dallo script. Sono due elementi diversi. Per fissarli entrambi, scarica lo script dal tag invece che da main, sostituendo main con v1.2.0 nell’URL.

Un’esecuzione riuscita stampa i percorsi in cui ha scritto i file, incluse queste due righe:

Installed runner: /home/you/.agentlas/runtime/current/bin/hephaestus
Installed shell commands in /home/you/.local/bin (add ~/.local/bin to PATH to use them)

La seconda riga viene spesso ignorata. In una nuova installazione di Ubuntu, ~/.local/bin spesso non è presente in PATH, quindi ogni comando hep-* restituisce command not found anche se l’installazione è riuscita. Correggi il problema e verifica:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
hep-global status

hep-global status indica che cosa ha installato il router globale e quali harness ha rilevato. Se viene eseguito, il valore di PATH è corretto.

Dove risiede lo stato

Nella directory home tutto è rappresentato da file, quindi il backup e la migrazione sono semplici.

• ~/.agentlas/runtime/v1.2.0/ contiene il runtime, mentre ~/.agentlas/runtime/current/ è un symlink alla versione attiva. È possibile mantenere affiancate due versioni bloccate.
• ~/.local/bin/ contiene i wrapper della shell: hephaestus, hep-build, hep-network, hep-search, hep-storm, hep-cloud e hep-upload.
• ~/.agentlas/networking/memory/ contiene la memoria persistente: playbook-registry.json, playbook-candidates.jsonl e memory-events.jsonl.
• ~/.agentlas/networking/hub-agents/<slug>/memory/experience.sqlite contiene l'esperienza per ogni agent, con ambito definito dal proprietario.
• <project>/.agentlas/ontology-runtime.sqlite contiene lo stato specifico del progetto, che quindi segue il repository invece del server.
• ~/.cache/agentlas/python contiene la cache Python su Linux. macOS usa un percorso diverso; è il ramo che l'installer seleziona con uname.

La documentazione della memoria specifica chiaramente che secret, credenziali in formato non elaborato e trascrizioni complete non devono essere inseriti in nessun ambito della memoria. I valori delle credenziali restano in file locali esclusi da git, mentre i record della memoria contengono soltanto nomi e percorsi. Eseguendo il backup di ~/.agentlas e delle directory di progetto .agentlas, è possibile ricostruire l'ambiente su un nuovo VPS.

A quali backend di modelli può collegarsi

Ecco il dettaglio che cambia la prospettiva sull’intera configurazione: Agentlas non chiama un’API del modello. A farlo è l’host harness.

Il documento sull’architettura descrive gli adattatori runtime che traducono un core per ciascun harness e specifica che il runtime host gestisce le credenziali del modello. Agentlas espone due componenti che un harness può utilizzare: un file AgentSkills e un server MCP (model context protocol) che comunica tramite stdio. Pertanto, la domanda «quali modelli supporta Agentlas» equivale in realtà a «quali modelli supporta il tuo harness»; la risposta è: tutti i modelli raggiungibili da Claude Code, Codex, opencode, goose o Hermes.

La registrazione del server MCP in una configurazione TOML in stile Codex è simile alla seguente:

[mcp_servers.hephaestus-network]
command = "~/.agentlas/runtime/current/bin/hephaestus"
args = ["mcp", "serve"]

Lo stesso server viene registrato automaticamente in ~/.cursor/mcp.json, ~/.config/goose/config.yaml e nelle altre configurazioni degli harness durante l’installazione. Se configuri più server di questo tipo su uno stesso host, eseguire server MCP su un VPS descrive più dettagliatamente il modello stdio e la gestione dei processi.

Indirizzalo a un endpoint Ollama self-hosted

Poiché l’harness gestisce la connessione al modello, per usare modelli locali con Agentlas devi configurare l’harness affinché utilizzi Ollama. In v0.15 Ollama ha aggiunto il sottocomando launch proprio per questo scopo, disponibile ancora nella versione v0.32.9 all’11 August 2026. Il comando configura un harness esistente per l’uso di modelli locali senza impostare variabili d’ambiente:

ollama pull qwen3-coder:30b
ollama launch opencode

Sostituisci claude, codex o droid a opencode, in base all’harness installato. Quindi inoltra una richiesta al runtime locale:

~/.agentlas/runtime/current/bin/hephaestus route "summarise the failing tests" --runtime ollama

Un instradamento riuscito restituisce una decisione JSON che identifica l’agente o il team selezionato, con un receipt_id. Se non restituisce dati utili, la causa più comune è la lunghezza del contesto. La documentazione di Agentlas richiede un modello con almeno 64k di contesto per le sessioni con molto routing e indica qwen3-coder, gemma3 e deepseek-r1 come esempi. Anche le indicazioni di Ollama per gli strumenti di sviluppo richiedono almeno 64k. Le decisioni di routing includono nel prompt l’inventario degli agenti. Di conseguenza, un modello con un contesto di 8k o 32k tronca l’inventario e seleziona l’agente in modo errato.

C’è una limitazione che lo slogan non indica. Ollama, Gemma e DeepSeek non dispongono di un proprio sistema di plugin o comandi. Per questo, i comandi slash /agentlas non sono disponibili. In una configurazione con modello locale, il sistema si utilizza tramite il server MCP e il comando hephaestus route. Questa è una riduzione effettiva delle funzionalità disponibili, ma è il compromesso necessario per mantenere i pesi sul proprio server.

Quanto costa in RAM un hub di specialisti inattivi

Niente. Questa è l'intera risposta, e puoi dimostrarla invece di fidarti.

Gli specialisti dell'hub importati arrivano come artefatti di pacchetto, non come processi. Uno specialista è un agent.md più una directory .agentlas/ di JSON: routing-card.json per trigger e funzionalità, memory-map.json per i limiti di scrittura, mode-map.json per indicare se viene eseguito da solo o in gruppo. Hephaestus Network è descritto come uno scheduler in-process, senza servizi in background. Tra un'attività e l'altra, verifica direttamente:

pgrep -af hephaestus
systemctl --user list-units --type=service | grep -i agentlas
du -sh ~/.agentlas

I primi due comandi non mostrano nulla su un sistema inattivo, perché non è presente alcun processo residente. Il terzo mostra l'unico costo che un hub parcheggiato impone: lo spazio su disco, che aumenta con il numero di specialisti conservati e con il modello di embedding incluso nella release del runtime.

La domanda sulla memoria riguarda quindi interamente il picco di carico, e il picco dipende dal tuo harness e dal backend del modello. Se l'harness comunica con un'API ospitata, il costo residente è un singolo processo da alcune centinaia di megabyte. Se ospiti autonomamente i pesi, sono i pesi a determinare il costo:

[
  {
    "label": "Hosted API model",
    "weights_gb": 0
  },
  {
    "label": "gemma3:4b",
    "weights_gb": 3.3
  },
  {
    "label": "gemma3:12b",
    "weights_gb": 8.1
  },
  {
    "label": "gemma3:27b",
    "weights_gb": 17
  },
  {
    "label": "qwen3-coder:30b",
    "weights_gb": 19
  }
]

Queste sono le dimensioni di download pubblicate nella libreria di modelli di Ollama, non misurazioni ottenute da un'esecuzione di benchmark; inoltre, la cache KV per un contesto da 64k si aggiunge a ogni valore superiore a zero riportato sopra. Il modello che la documentazione di Agentlas indica per primo, qwen3-coder:30b, richiede 19 GB di pesi prima di considerare il contesto; persino la variante Gemma 27B richiede 17 GB. Rispetto a questi valori, il livello Agentlas non incide sul budget.

Confronto con l'esecuzione di un solo harness

Esegui un solo harness con un'API ospitata e il tuo VPS esegue un processo. Aggiungi Agentlas e continua a eseguire lo stesso processo, oltre a gestire i file. L'orchestrator non è un programma aggiuntivo a esecuzione permanente: è un prompt più grande, assemblato a partire dai package presenti su disco e poi eliminato.

Il costo che cambia riguarda il context, non la memoria. Un orchestrator che carica diverse specialist card e i relativi routing metadata usa più token per attività rispetto a un harness minimale; con un'API ospitata questo si traduce in un costo economico, non in maggiore utilizzo della RAM. Con i local weights, invece, si traduce in più tempo, perché un prompt più lungo richiede un prefill più lungo sulla CPU o impegna maggiormente la GPU.

Per questo il dimensionamento di un server come questo dipende dalla scelta del modello, non dall'agent framework. Dimensionare RAM e CPU per un coding agent VPS descrive il tema in dettaglio e la conclusione vale anche in questo caso: scegli il piano in base al backend che intendi eseguire, poi aggiungi un paio di gigabyte di margine per l'harness. Se invece vuoi confrontarlo con il design di un supervisor sempre attivo, l'harness multi-agent Omnigent mantiene il coordinator residente. È una scelta opposta, il cui effetto è visibile direttamente nella memoria utilizzata a riposo.

Modalità di errore e stringhe visualizzate

hep-build: command not found subito dopo un'installazione pulita. L'installer ha scritto in ~/.local/bin, che non si trova in PATH in un'immagine Ubuntu predefinita. Lo indicava nell'ultima riga, ma la riga è uscita dalla schermata. Aggiungi l'export mostrato sopra.

Il comportamento cambia dopo la ricostruzione del server. Non hai impostato HEPHAESTUS_REF, quindi l'installer ha usato il tag predefinito, che quel giorno era quello corrente. Fissalo e annota il valore insieme agli altri numeri di versione.

Il routing seleziona lo specialista sbagliato con un modello locale. La context window del modello è troppo piccola per l'inventario degli agenti. Passa a un modello con almeno 64k e imposta la context length di Ollama allo stesso valore, perché il valore predefinito è inferiore a quello richiesto dagli strumenti di coding.

ollama launch non viene riconosciuto. Il subcommand è stato introdotto in Ollama v0.15. I pacchetti meno recenti provenienti da un repository della distribuzione sono precedenti a questa versione; installa quindi una versione aggiornata di Ollama.

L'installazione scrive in harness che non ti aspettavi. Lo script rileva e configura ogni harness trovato, scrivendo in ~/.claude/, ~/.codex/, ~/.gemini/, ~/.cursor/ e altri percorsi. Su un build server condiviso, leggi lo script prima di eseguirlo e individua le directory che ti interessano.

Eseguirlo già ora?

Un progetto di dieci settimane, con rilasci automatici più volte al giorno, non è adatto a un carico di produzione. L'architettura è realmente interessante, la licenza è Apache-2.0 e il design basato su file consente di disinstallarlo eliminando due directory. Questi aspetti lo rendono economico da provare, ma costoso da usare come dipendenza.

Per ora, una scelta ragionevole è fissare la versione v1.2.0, eseguirlo su un server che si possa ricreare, includere ~/.agentlas nei backup e rileggere il changelog prima di modificare il vincolo di versione. Per una panoramica più ampia delle alternative disponibili in questo ambito e del relativo livello di maturità, la panoramica degli agenti AI self-hosted è il punto di partenza migliore; eseguire in self-hosting un agente Hermes su un VPS descrive invece uno degli harness a cui Agentlas si adatta.

FAQ

Agentlas OS viene eseguito come server sulla mia VPS?

No. Nel repository non sono presenti demoni, porte in ascolto o immagini di container. L'installer scrive un runtime in ~/.agentlas/runtime/ e i wrapper dei comandi in ~/.local/bin. Hephaestus Network è uno scheduler eseguito in-process, non un servizio in background. Puoi verificarlo su un sistema inattivo: pgrep -af hephaestus non stampa nulla e non esiste alcuna unità systemd da abilitare. In questo caso, il self-hosting significa che il codice e lo stato si trovano sulla tua macchina, non che sia in ascolto un servizio.

Quanta RAM utilizza un hub di specialisti inattivi?

Nessuna, perché gli specialisti inattivi non sono processi. Uno specialista è un file agent.md più una directory .agentlas/ che contiene routing-card.json, memory-map.json e metadati simili. Di conseguenza, un hub inattivo occupa spazio su disco. Misuralo con du -sh ~/.agentlas. La memoria viene consumata solo durante l'esecuzione di un'attività. A consumarla sono il processo dell'harness e il backend del modello, non il livello Agentlas.

Quali modelli posso usare e posso collegarlo al mio Ollama?

Agentlas non chiama direttamente le API dei modelli. Le credenziali e la connessione sono gestite dall'harness dell'host. I modelli supportati sono quindi quelli supportati dal tuo harness. Per usare pesi locali, esegui ollama launch opencode sostituendo claude, codex o droid. Il comando configura l'harness per usare il tuo server Ollama senza variabili d'ambiente. Usa un modello con un contesto di almeno 64k, ad esempio qwen3-coder o gemma3, perché i prompt di routing contengono l'inventario degli agenti e vengono troncati in modo significativo con finestre di contesto più piccole.

Quale versione devo installare e perché è importante fissarla?

Installa v1.2.0, la release contrassegnata come corrente il 12 August 2026, impostando HEPHAESTUS_REF=v1.2.0 prima di eseguire l'installer. Il valore predefinito dello script è version="${HEPHAESTUS_REF:-v1.2.0}" e segue il tag successivo pubblicato dai maintainer. Fissare la versione è più importante del solito perché il progetto ha pubblicato oltre cento release nella serie 1.1, talvolta diverse nello stesso giorno. Di conseguenza, una nuova build non fissata eseguita dopo alcune settimane non fornirà il sistema che avevi testato.