100monkeys.ai

Blog · Guida · 28 ottobre 2026

Installare AEGIS su un VPS Ubuntu nuovo ed eseguire il primo task approvato

Anche in: English, Español, Português, 日本語, Deutsch, Français, 한국어, 简体中文, हिन्दी · Tutte le guide in italiano

Trasparenza: AEGIS è sviluppato da 100monkeys.ai, quindi leggete questa guida come il resoconto di chi lo costruisce. L'ha scritta in bozza uno dei nostri agenti di IA a partire dalla documentazione pubblica di AEGIS su docs.100monkeys.ai (in inglese) e l'azienda l'ha rivista; questa edizione italiana è una traduzione della guida originale in inglese. Ogni comando qui sotto è copiato da quella documentazione o dalla nostra home page. Non abbiamo eseguito esattamente questa sequenza su un VPS nuovo per scrivere la guida, e dove la documentazione si contraddice lo diciamo invece di tirare a indovinare.

AEGIS by 100monkeys.ai, in beta, è un orchestratore self-hosted che esegue agenti autonomi in runtime isolati, con policy applicate e stato persistente. Questa guida porta un server Ubuntu nuovo fino a uno stack locale funzionante, poi esegue un agente dietro un gate di approvazione umana: il lavoro dell'agente si ferma e aspetta finché non rispondete sì.

Prima di iniziare

Sappiate a cosa serve l'installazione rapida. La pagina Getting Started lo dice chiaramente: aegis init "is designed for local testing and evaluation only. It uses an in-memory secrets store and does not deploy Keycloak (IAM) or OpenBao (secrets management)." (è pensato solo per test locali e valutazione; usa un archivio di segreti in memoria e non installa Keycloak (IAM) né OpenBao (gestione dei segreti).) La pagina Infrastructure Requirements indica come IAM "None (unauthenticated)" (nessuno, senza autenticazione) e come TLS "None" (nessuno). Per la produzione la documentazione rimanda invece al repository aegis-deploy.

Quindi, su un VPS, trattate questo stack come un laboratorio privato. I controlli di salute della CLI usano per default l'host 127.0.0.1 e la porta 8088. Non aprite quella porta a internet; raggiungete la macchina via SSH.

Vi servono:

Passo 1. Eseguire l'installer

Copiate la riga da 100monkeys.ai, dove è stampata, ed eseguitela con il vostro utente normale:

curl -fsSL https://get.100monkeys.ai | bash

Se preferite, leggete prima lo script. La documentazione dice che https://get.100monkeys.ai reindirizza a install.sh sul branch main di aegis-orchestrator. Su Linux installa curl, ca-certificates e fuse3 se mancano, installa libfuse3 dove il binario ne ha bisogno e installa Docker Engine (docker-ce) se Docker non c'è. Se Docker gira ma il vostro utente non vi accede, vi aggiunge al gruppo docker. Poi installa aegis in /usr/local/bin/aegis e avvia lo stack con aegis up --tag <version>.

Per fissare una release, impostate AEGIS_VERSION su un tag di release prima di eseguirlo; la documentazione elenca ogni pacchetto pubblicato nella pagina Releases.

Passo 2. Controllare il binario e lo stack

aegis --version
aegis status

aegis status riporta lo stato di salute dello stack locale. Se durante l'installazione siete stati aggiunti al gruppo docker, uscite e rientrate perché le nuove shell abbiano il gruppo.

Passo 3. Eseguire la configurazione guidata e scegliere un provider di modelli

aegis init

Il wizard "prepares stack files, configures the node, starts Docker Compose services, verifies health, and can optionally load smoke-test agents" (prepara i file dello stack, configura il nodo, avvia i servizi Docker Compose, verifica lo stato e, se volete, carica agenti di smoke test). Accettate lo smoke test hello-world quando ve lo chiede; il passo successivo lo usa. La configurazione che scrive associa gli alias di modello default, smart, judge e tool-judge al provider scelto. L'agente hello-world usa smart, e un alias che il nodo non associa fallisce con Model alias '<alias>' not found, quindi completate la domanda sul provider. I file dello stack vanno in ~/.aegis a meno che non passiate --dir.

Passo 4. Eseguire hello-world una volta, senza supervisione

Dimostrate che il ciclo funziona prima di aggiungere un gate:

aegis task execute hello-world \
  --input '{"task": "Write a Python function that returns the Fibonacci sequence up to n."}' \
  --follow

--follow trasmette gli eventi di iterazione. L'agente genera codice, esegue la validazione e o riesce o si raffina attraverso le iterazioni finché i suoi validatori non passano.

Passo 5. Scrivere un workflow con un gate di approvazione

In AEGIS un'approvazione è uno stato del workflow di tipo kind: Human. Salvate questo come approved-task.yaml. Segue la forma dell'esempio della pagina Building Workflows, ridotto a un agente e un gate:

apiVersion: 100monkeys.ai/v1
kind: Workflow
metadata:
  name: approved-task
  version: "1.0.0"
  description: "One agent drafts, a person approves, then the run completes."
spec:
  initial_state: DRAFT
  states:
    DRAFT:
      kind: Agent
      agent: hello-world
      timeout: 600s
      transitions:
        - condition: on_success
          target: APPROVE
        - condition: on_failure
          target: FAILED
    APPROVE:
      kind: Human
      prompt: |
        Draft:
        {{DRAFT.output}}

        Approve? (yes/no)
      timeout: 86400s
      transitions:
        - condition: input_equals_yes
          target: DONE
        - condition: input_equals_no
          target: FAILED
    DONE:
      kind: System
      command: "echo 'Approved'"
      transitions: []
    FAILED:
      kind: System
      command: "echo 'Rejected or failed'"
      transitions: []

Passo 6. Fare il deploy e avviare un'esecuzione

aegis workflow deploy ./approved-task.yaml --force
aegis workflow run approved-task \
  --input '{"task": "Write a Python function that returns the Fibonacci sequence up to n."}'

Il comando run stampa un id di esecuzione. Seguitelo:

aegis workflow logs <execution-id> --follow --verbose
aegis workflow executions get <execution-id>

Quando la bozza è pronta, executions get mostra lo stato corrente come APPROVE (WAITING FOR HUMAN SIGNAL). Niente dopo il gate viene eseguito finché qualcuno non risponde.

Passo 7. Leggere la bozza, poi rispondere

aegis workflow signal <execution-id> --response yes

Rispondete no per mandare invece l'esecuzione in FAILED. Un gate a cui nessuno risponde scade dopo il suo timeout; con il comportamento predefinito l'esecuzione viene segnata come fallita con il motivo human_input_timeout.

Una cosa da sapere: la documentazione non concorda sulla parola. La pagina Human Approvals dice che un gate sì/no accetta le risposte ["yes", "no"]; la pagina Building Workflows invia il segnale con --response approved; la pagina della CLI mostra --response "approve". Noi usiamo yes perché è la parola da cui prende nome la transizione input_equals_yes. Se l'esecuzione non avanza, controllate executions get e provate le altre forme.

Cosa non copre questa guida

E poi

Per il ragionamento dietro il gate, leggete How to give an orchestrator an approval step (in inglese). Per cosa registrare intorno a ogni esecuzione, leggete Una checklist di tracciabilità per agenti di IA in produzione. Se volete le note e il codice dei vostri agenti in un unico registro che possono leggere e scrivere via MCP, vedete Collegare Claude Code a Carbon Forge via MCP.

Installa AEGIS da 100monkeys.ai