Prima di AgentBox                    Dopo AgentBox
─────────────────                  ──────────────
Agente → disco completo ❌           Agente → solo percorsi consentiti ✅
Agente → tutta la rete ❌           Agente → solo host consentiti ✅
Agente → segreti grezzi ❌          Agente → token con ambito limitato ✅
Nessun registro di audit ❌         Ogni azione registrata ✅
Nessun interruttore di emergenza ❌ Kill in <100ms ✅
Le skill girano come root ❌        Sandbox isolato a livello di kernel ✅

# Installazione
go install github.com/siyad01/agentbox/cmd/agentbox@latest

# Valida un manifest prima di eseguirlo
agentbox validate manifests/email-sorter.yaml

# Esegui un agente in un sandbox
agentbox run --manifest manifests/email-sorter.yaml python agent.py

# Visualizza cosa ha fatto l'agente
agentbox audit --log logs/email-sorter-audit.log

# Verifica che il registro non sia stato manomesso
agentbox verify logs/email-sorter-audit.log

# Gestisci i segreti
agentbox vault add ANTHROPIC_API_KEY
agentbox vault list

name: "email-sorter"
version: "1.0.0"
description: "Legge la casella di posta, categorizza le email, scrive nella cartella ordinata"
runtime: docker        # oppure: gvisor (livello kernel), firecracker (MicroVM)

permissions:
  filesystem:
    read:
      - "~/Documents/inbox"
    write:
      - "~/Documents/sorted"
    deny:                      # SEMPRE bloccato — anche se nella lista di lettura
      - "~/.ssh"
      - "~/.aws"
      - "~/.config"
      - "/etc"

  network:
    allow:
      - "api.anthropic.com"
      - "gmail.googleapis.com"
    deny:
      - "*"                    # blocca tutto il resto

  tools:
    allow:
      - "read_file"
      - "write_file"
      - "list_*"
    deny:
      - "execute_shell"        # nessun accesso alla shell, mai
      - "*_delete"             # nessuno strumento di eliminazione

  credentials:
    - ANTHROPIC_API_KEY        # iniettato dal vault a runtime
    - GMAIL_TOKEN              # l'agente non vede mai il valore grezzo

limits:
  max_tokens:    50000         # budget token LLM
  max_duration:  "30m"         # terminato dopo 30 minuti
  max_memory_mb: 256           # tetto RAM
  max_requests:  500           # massimo invocazioni di strumenti

audit:
  log_level: full
  alert_on:
    - filesystem_deny
    - network_deny
    - token_budget_80pct
  log_path: "logs/email-sorter-audit.log"

agentbox run --manifest agent.yaml python agent.py
         │
         ▼
┌─────────────────────────────────────────────────────┐
│                 Policy Engine                        │
│  Analizza il manifest → costruisce liste allow/deny │
│  Valida le firme → rifiuta skill non firmate        │
│  Inietta le credenziali dal vault                   │
└──────────────────────┬──────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│              Isolation Layer                         │
│                                                     │
│  Docker  → container + seccomp + cap-drop           │
│  gVisor  → kernel in user-space, intercettazione syscall │
│  Firecracker → kernel MicroVM dedicato per agente   │
│                                                     │
│  Filesystem: solo i percorsi dichiarati montati     │
│  Rete:    solo gli host dichiarati raggiungibili    │
│  Capacità: TUTTE rimosse, nessuna aggiunta          │
└──────────────────────┬──────────────────────────────┘
                       │
          ┌────────────┼────────────┐
          ▼            ▼            ▼
   Audit Logger   Credential    Resource
   (hash-chain)     Vault       Monitor
   ogni azione   AES-256-GCM  auto-kill
   registrata    token con    su limite
                 ambito limitato

L'agente tenta: write("/home/user/.ssh/id_rsa")
                    │
                    ▼
         kernel in user-space di gVisor
                    │
         Il percorso è nella lista deny? → SÌ
                    │
                    ▼
         EPERM restituito immediatamente
         Il kernel host non vede mai questa syscall
         L'iniezione di prompt non può attraversare questo livello

agentbox <comando> [opzioni]

Comandi:
  run       Esegui un agente in un sandbox
  validate  Valida un file manifest
  kill      Termina un agente in esecuzione
  audit     Visualizza i registri di audit dell'agente
  verify    Verifica l'integrità del registro di audit
  vault     Gestisci le credenziali crittografate
  serve     Avvia il server API REST
  version   Mostra la versione

Esempi:
  agentbox validate manifests/email-sorter.yaml
  agentbox run --manifest manifests/email-sorter.yaml python agent.py
  agentbox kill agent-abc123
  agentbox audit --log logs/email-sorter.log --deny
  agentbox audit --log logs/email-sorter.log --last 1h
  agentbox verify logs/email-sorter.log
  agentbox vault add ANTHROPIC_API_KEY
  agentbox vault list
  agentbox vault delete OLD_KEY
  agentbox serve :8081

# Elenca gli agenti in esecuzione
curl http://localhost:8081/api/agents

# Avvia un agente
curl -X POST http://localhost:8081/api/agents \
  -H "Content-Type: application/json" \
  -d '{"manifest":"manifests/email-sorter.yaml","command":["python","agent.py"]}'

# Termina un agente
curl -X DELETE http://localhost:8081/api/agents/abc123

# Interroga il registro di audit
curl "http://localhost:8081/api/audit?deny=true&agent=email-sorter"

{"id":1,"hash":"a3f2...","prev_hash":"genesis","timestamp":"2026-05-05T09:00:00Z","agent_id":"abc123","agent_name":"email-sorter","event_type":"agent_start","allowed":true,"resource":"manifests/email-sorter.yaml"}
{"id":2,"hash":"b7c1...","prev_hash":"a3f2...","timestamp":"2026-05-05T09:00:01Z","agent_id":"abc123","agent_name":"email-sorter","event_type":"filesystem_allow","allowed":true,"resource":"read:/home/user/Documents/inbox/mail.txt","rule":"filesystem.read: ~/Documents/inbox"}
{"id":3,"hash":"d9e4...","prev_hash":"b7c1...","timestamp":"2026-05-05T09:00:01Z","agent_id":"abc123","agent_name":"email-sorter","event_type":"filesystem_deny","allowed":false,"resource":"read:/home/user/.ssh/id_rsa","rule":"filesystem.deny: ~/.ssh","reason":"path is explicitly denied"}

agentbox verify logs/email-sorter-audit.log

✅ Il registro di audit è integro
   Voci: 47 (ID 1–47)
   Catena hash: ininterrotta

# Memorizza un segreto (mai registrato, mai in chiaro nelle variabili d'ambiente)
agentbox vault add ANTHROPIC_API_KEY

# Elenca i nomi delle credenziali memorizzate (i valori non vengono mai mostrati)
agentbox vault list

# Verifica che una credenziale possa essere decrittata
agentbox vault test ANTHROPIC_API_KEY

# Ruota una credenziale
agentbox vault add ANTHROPIC_API_KEY   # add aggiorna le credenziali esistenti

# Questo agente è configurato con max_duration: 5s
agentbox run --manifest manifests/timeout-test.yaml python long_running_agent.py

Agent started
tick 1
tick 2
tick 3
tick 4
tick 5
🛑 Killing agent timeout-test: duration limit exceeded: 5s
⚠️  Agent timeout-test exited code 137 in 5.2s

# Clona
git clone https://github.com/siyad01/agentbox
cd agentbox

# Compila
go build -o agentbox ./cmd/agentbox/

# Esegui i test (27 test, tutti superati)
go test ./...

# Installa globalmente
go install ./cmd/agentbox/

agentbox/
├── cmd/agentbox/main.go          ← punto di ingresso CLI
├── internal/
│   ├── policy/
│   │   ├── manifest.go           ← schema manifest YAML
│   │   ├── parser.go             ← validazione + valori predefiniti
│   │   └── engine.go             ← motore decisionale deny-first (20 test)
│   ├── audit/
│   │   ├── logger.go             ← registro append-only con catena hash SHA-256
│   │   ├── verifier.go           ← rilevamento manomissioni
│   │   └── reader.go             ← query + filtro
│   ├── vault/
│   │   ├── store.go              ← archivio credenziali crittografato AES-256-GCM
│   │   └── injector.go           ← iniezione a runtime (7 test)
│   ├── sandbox/
│   │   ├── sandbox.go            ← interfaccia Sandbox
│   │   ├── docker.go             ← backend Docker
│   │   ├── gvisor.go             ← backend gVisor (livello kernel)
│   │   ├── manager.go            ← gestione del ciclo di vita degli agenti
│   │   └── util.go               ← rilevamento WSL2, helper percorsi
│   ├── monitor/
│   │   └── enforcer.go           ← limiti delle risorse + auto-kill
│   └── api/
│       └── server.go             ← API REST su :8081
└── manifests/
    ├── email-sorter.yaml         ← esempio di produzione
    └── timeout-test.yaml         ← esempio di applicazione dei limiti