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 è realmente maturo questo progetto

Il repository è stato creato il 4 giugno 2026. Al 13 ottobre 2026 ha circa quattro mesi, con approssimativamente 1,580 stelle e 110 fork. È un progetto giovane per un uso in ambienti reali.

La frequenza dei rilasci conta più 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 più di cento rilasci contrassegnati, diversi nello stesso giorno, tramite automazione. La serie 1.2 ha mantenuto lo stesso ritmo: al 10 ottobre 2026 aveva raggiunto la versione v1.2.62. Un progetto che procede a questa velocità può modificare il proprio comportamento tra un martedì e un giovedì.

Quindi, fissa la versione del rilascio. A questo scopo, l'installer legge una variabile d'ambiente, utilizzata in tutta la guida seguente. Un'installazione senza versione fissata di un progetto che pubblica rilasci con questa frequenza installa la versione contrassegnata più di recente quando lo script è stato modificato l'ultima volta.

Cosa serve sul VPS

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

• Un VPS Linux. Ubuntu 24.04 è una buona base. L'installer rileva il sistema operativo con uname -s e, su Linux, segue un ramo diverso da macOS; è quindi supportato anche un server headless.
• curl, tar e git sul server, oltre a Python 3.9 o versioni successive, che l'installer attuale usa per verificare l'archivio della release.
• Accesso HTTPS in uscita verso raw.githubusercontent.com e github.com per un'installazione normale. L'installer scarica un archivio della release e ne verifica l'hash SHA-256. Un server senza accesso in uscita può comunque eseguire l'installazione da un albero dei sorgenti copiato manualmente: impostare HEPHAESTUS_SOURCE_DIR su tale percorso. Lo script salta il download, perché il requisito curl si applica solo alle installazioni da una release remota.
• Un host harness, cioè l'agente di coding che comunica effettivamente con un modello. Claude Code, Codex, opencode, goose e Hermes sono tutti adapter supportati.

Non è necessario usare root. L'installer scrive soltanto nella directory home dell'utente, incluso ~/.local/bin. Se un passaggio non riesce, ad esempio perché un percorso non è scrivibile, mostra un avviso e continua con le operazioni restanti. Al termine restituisce comunque un codice diverso da zero se si è verificato un errore. Se non hai ancora scelto il server, eseguire un agente di coding su un VPS descrive l'immagine di base e la configurazione dell'accesso su cui si basa questa procedura.

Installare la release bloccata

Il README upstream documenta una singola riga che inoltra uno script da main direttamente a 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. Nello script disponibile su main, la riga è ora version="${HEPHAESTUS_REF:-v1.2.62}" e v1.2.62 è stata pubblicata il 10 ottobre 2026. Lasciare la variabile non impostata non installa più v1.2.0 e il valore predefinito continuerà a cambiare con ogni tag. Impostala esplicitamente: una ricostruzione eseguita tra alcuni mesi installerà ciò che hai testato.

Un limite da considerare: l'URL dello script sopra segue main, mentre HEPHAESTUS_REF blocca il payload del runtime scaricato dallo script. Sono due aspetti distinti. Per bloccarli entrambi, scarica lo script dal tag invece che da main, sostituendo main con v1.2.0 nell'URL.

Il pin riguarda l'installazione, non ciò che accade in seguito. Fino a v1.2.0 e su main, i comandi hephaestus avviano un controllo degli aggiornamenti in background che, se è disponibile una release più recente, la installa e ricollega ~/.agentlas/runtime/current senza chiedere conferma. L'installer disabilita questo comportamento durante la propria esecuzione con HEPHAESTUS_AUTO_UPDATE=0, e la stessa variabile consente di mantenere il pin. Verrà aggiunta al profilo della shell nel passaggio successivo.

Un'esecuzione completata correttamente stampa i percorsi in cui ha scritto, incluse queste righe:

Installed runner: /home/you/.agentlas/runtime/current/bin/hephaestus
Installed shell commands in /home/you/.local/bin
  /home/you/.local/bin is not on your PATH yet. To use them by name:

L'avviso relativo a PATH è la riga che spesso viene ignorata. In un'installazione Ubuntu appena creata, ~/.local/bin spesso non è presente in PATH, quindi ogni comando hep-* termina con command not found anche se l'installazione è riuscita. Il suggerimento dell'installer aggiunge la configurazione a ~/.zshrc, ma la shell predefinita di Ubuntu è bash. Correggila in quel file, disattiva contemporaneamente l'aggiornamento in background e verifica:

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

hep-global è la forma originale di hephaestus global, mentre status mostra se ogni file di istruzioni dell'harness contiene il blocco del router gestito. Il router è disattivato per impostazione predefinita, quindi è normale che il comando indichi che non ne è presente alcuno. Se il comando viene eseguito, PATH è corretto.

Dove risiede lo stato

Tutto è un file nella directory home dell’utente, quindi backup e migrazione sono semplici.

• ~/.agentlas/runtime/1.2.0/ contiene il runtime, con il v iniziale rimosso dal tag dall’installer; ~/.agentlas/runtime/current/ è un symlink alla versione attiva. Due versioni bloccate possono coesistere.
• ~/.local/bin/ contiene i wrapper della shell, inclusi 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 specifica di ogni agente, nell’ambito del relativo proprietario.
• <project>/.agentlas/ontology-runtime.sqlite contiene lo stato specifico del progetto, quindi viene trasferito insieme al repository anziché restare legato al server.
• ~/.cache/agentlas/python contiene la cache Python su Linux. macOS usa un percorso diverso; l’installer seleziona il ramo corrispondente tramite uname.

La documentazione della memoria per v1.2.0 specifica chiaramente che secret, credenziali in chiaro e trascrizioni complete non devono essere inseriti in alcun ambito della memoria. I valori delle credenziali restano in file locali esclusi da git tramite gitignore, mentre i record della memoria contengono soltanto nomi e percorsi. Esegui il backup di ~/.agentlas e delle directory .agentlas dei progetti per poter ricostruire l’ambiente su un nuovo VPS.

Un solo elemento lascia il server: secondo il README attuale, hep-build invia per impostazione predefinita contatori anonimi delle build, senza prompt, percorsi o contenuti degli agenti. Imposta AGENTLAS_TELEMETRY=0 o DO_NOT_TRACK=1, oppure inserisci "telemetry": false in ~/.agentlas/networking/config.json, per disattivare questa funzione.

A quali backend di modelli può collegarsi

Ecco il dettaglio che modifica la lettura dell’intera configurazione: Agentlas non chiama un’API del modello. Se ne occupa l’host harness.

Il documento sull’architettura descrive adattatori di runtime che traducono un componente principale per ciascun harness. Il README specifica che l’adattatore gestisce l’autenticazione presso il provider, mentre il chiamante fornisce il proprio modello e l’accesso all’API. Agentlas mette a disposizione 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 devi collegare più server di questo tipo a un unico host, eseguire server MCP su un VPS descrive più in dettaglio il modello stdio e dei processi.

Indirizzalo a un endpoint Ollama self-hosted

Poiché l’harness gestisce la connessione al modello, per usare modelli locali con Agentlas devi indirizzare l’harness a Ollama. Ollama ha aggiunto un sottocomando launch nella versione v0.15 proprio per questo scopo, disponibile ancora nella versione v0.32.9 all’11 agosto 2026. Configura un harness esistente per usare 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. Inoltra quindi una richiesta tramite il runtime locale:

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

Un inoltro riuscito restituisce una decisione JSON che indica l’agente o il team selezionato, insieme a un receipt_id. Se non restituisce informazioni utili, la causa più comune è la lunghezza del contesto. La documentazione sui modelli locali della versione v1.2.0 richiede un modello con almeno 64k di contesto per le sessioni incentrate sul 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’è un limite che lo slogan non evidenzia. Ollama, Gemma e DeepSeek non dispongono di un sistema proprietario di plugin o comandi, quindi i comandi slash /agentlas non sono disponibili. In una configurazione con modelli locali, il sistema viene gestito tramite il server MCP e il comando hephaestus route. È una riduzione effettiva delle funzionalità disponibili e il compromesso necessario per mantenere i pesi sul proprio server.

Quanto costa in RAM un hub di specialisti inattivi

Nulla. Questa è la risposta completa, e puoi verificarla invece di fidarti.

Gli specialisti dell'hub vengono aggiunti come artefatti di pacchetto, non come processi. Uno specialista è un agent.md con una directory .agentlas/ di file 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 team. La documentazione di Hephaestus Network descrive un runner che avvia i worker per un'attività. Non indica alcuna apertura di una porta in ascolto né richiede di abilitare un servizio. 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 stampano nulla su un host inattivo, perché non è presente alcun processo residente. L'unica eccezione è l'updater in background: se HEPHAESTUS_AUTO_UPDATE=0 non è impostato, un comando può lasciare in esecuzione un worker di aggiornamento distaccato e di breve durata dopo il proprio termine. Il terzo comando mostra l'unico costo imposto da un hub inattivo: lo spazio su disco. Questo costo aumenta con il numero di specialisti conservati e con il modello di embedding incluso nella distribuzione del runtime.

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

[
  {
    "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 durante un benchmark. Inoltre, la cache KV per un contesto da 64k si aggiunge a ogni valore superiore a zero riportato sopra. Il modello indicato per primo nella documentazione di Agentlas, qwen3-coder:30b, richiede 19 GB di pesi prima di considerare il contesto. Anche la variante Gemma 27B richiede 17 GB. Rispetto a questi valori, il livello Agentlas non incide sul budget di memoria.

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. Il programma di installazione ha scritto in ~/.local/bin, che in un'immagine Ubuntu predefinita non si trova in PATH. Lo ha indicato verso la fine dell'output, ma l'avviso è passato rapidamente e la correzione suggerita riguarda ~/.zshrc anziché bash. Aggiungi l'export mostrato sopra a ~/.bashrc.

Il comportamento cambia dopo la ricostruzione del sistema. Non hai impostato HEPHAESTUS_REF, quindi il programma di installazione ha usato il tag predefinito indicato dallo script in quel momento. Fissa il valore e registra questa versione insieme agli altri numeri di versione.

Il comportamento cambia senza ricostruire il sistema. L'updater in background ha installato una release più recente e ha spostato ~/.agentlas/runtime/current su quella versione. Verifica a cosa punta current e imposta HEPHAESTUS_AUTO_UPDATE=0 nell'ambiente in cui viene eseguito il tuo harness, non soltanto in una shell interattiva.

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

ollama launch non viene riconosciuto. Il sottocomando è stato introdotto in Ollama v0.15. I pacchetti meno recenti provenienti da un repository della distribuzione sono precedenti a questa versione, quindi installa 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, e modifica i file di configurazione già esistenti, come ~/.codex/config.toml, mantenendo un backup accanto all'originale. Su un build box condiviso, leggi lo script prima di eseguirlo e individua le directory che ti interessano.

Per ora, è il caso di usarlo?

Un progetto di quattro mesi con release automatizzate, talvolta diverse nello stesso giorno, non è ancora adatto a un carico di produzione. L’architettura è realmente interessante, la licenza è Apache-2.0 e tutto lo stato viene salvato in file di cui è possibile eseguire il backup. La rimozione è meno ordinata di quanto questo lasci intendere: il README non documenta alcuna procedura di disinstallazione, l’installer scrive in circa dieci percorsi all’interno della home directory e modifica le configurazioni degli harness esistenti. Inoltre, l’unico comando di rimozione indicato, hephaestus global remove, elimina soltanto il blocco router opzionale. Questi aspetti rendono poco costoso provarlo su una macchina usa e getta, ma costoso farvi affidamento.

Per ora, una posizione ragionevole è fissare v1.2.0, impostare HEPHAESTUS_AUTO_UPDATE=0 in modo che il vincolo venga mantenuto, eseguirlo su una macchina che sia possibile ricreare, includere ~/.agentlas nei backup e rileggere il changelog prima di spostare il vincolo. Per una panoramica più ampia delle altre soluzioni disponibili in questo ambito e del livello di maturità di ciascuna, 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 sul mio VPS?

No. Nel repository non sono presenti demoni, porte in ascolto o immagini di container. L'installer scrive il runtime in ~/.agentlas/runtime/ e i wrapper dei comandi in ~/.local/bin. Hephaestus Network viene eseguito quando un task lo avvia, non come servizio in background. Puoi verificarlo su un sistema inattivo: pgrep -af hephaestus non restituisce alcun output e non esiste alcuna unità systemd da abilitare. L'unica attività in background è un worker di aggiornamento di breve durata che i comandi possono avviare; HEPHAESTUS_AUTO_UPDATE=0 lo disabilita. In questo caso, il self-hosting significa che il codice e lo stato si trovano sulla tua macchina, non che un servizio sia in ascolto.

Quanta RAM utilizza un hub con 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. Un hub inattivo occupa quindi spazio su disco. Misuralo con du -sh ~/.agentlas. La memoria viene utilizzata solo durante l'esecuzione di un task. Il consumo è dovuto al processo dell'harness e al backend del modello, non al 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. Sono quindi supportati tutti i modelli supportati dal tuo harness. Per utilizzare pesi locali, esegui ollama launch opencode sostituendo claude, codex o droid. Questo configura l'harness per 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 includono l'inventario degli agenti e vengono troncati gravemente con finestre di contesto più piccole.

Quale versione devo installare e perché è importante fissare la versione?

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 in main è ora version="${HEPHAESTUS_REF:-v1.2.62}". La v1.2.62 è la release più recente, pubblicata il 10 October 2026, e questo valore predefinito cambia a ogni nuovo tag. Fissare la versione è più importante del solito perché il progetto ha pubblicato oltre cento release nella serie 1.1, diverse anche nella stessa giornata. Una ricompilazione non fissata eseguita dopo alcune settimane non fornirà quindi il sistema che hai testato. Imposta anche HEPHAESTUS_AUTO_UPDATE=0, perché in caso contrario il runtime installa release più recenti in background e il vincolo di versione smette silenziosamente di essere applicato.