agentsh

Nota per macOS: l'applicazione nativa delle policy su macOS tramite ESF (Endpoint Security Framework) + NE (Network Extension) è in Alpha. Funziona end-to-end — gli eventi di file, processi e rete fluiscono dall'estensione di sistema al motore policy Go — ma aspettatevi spigoli da rifinire e modifiche sostanziali tra le release. Per l'uso in produzione oggi raccomandiamo Linux.

Nota per Windows: stiamo lavorando per far firmare i driver minifilter. Fino ad allora, per l'uso in produzione è pienamente supportata solo la modalità WSL2 di Windows.

Gateway di esecuzione sicuro e controllato da policy per agenti AI.

agentsh si posiziona sotto il tuo agente/strumentazione — intercettando le attività su file, rete, processi e segnali (inclusi gli alberi dei sottoprocessi), applicando la policy che definisci ed emettendo eventi di audit strutturati.

Nota sulle piattaforme: Linux offre l'applicazione completa delle policy (punteggio di sicurezza 100%). macOS ESF+NE (punteggio 90%) è in Alpha — funzionale ma non pronto per la produzione. Windows WSL2 offre la stessa applicazione completa equivalente a Linux (punteggio 100%); il supporto nativo di Windows tramite driver minifilter + AppContainer (punteggio 85%) è in attesa della firma del driver. Consulta la Matrice di confronto piattaforme per i dettagli.

---

Cos'è agentsh?

• Endpoint shell/exec sostitutivo che trasforma ogni comando (e i suoi sottoprocessi) in eventi auditabili.
• Motore di policy per operazione: allow, deny, approve (approvazione umana), soft_delete o redirect.
• Visibilità I/O completa:
  • apertura/lettura/scrittura/eliminazione file
  • connessioni di rete + DNS
  • avvio/uscita processi
  • attività PTY
  • richieste API LLM con DLP e monitoraggio utilizzo
  • traffico database di famiglia Postgres tramite db_services dichiarati
  • invio/blocco segnali (applicato su Linux, solo audit su macOS/Windows)
  • query di database tramite il proxy PostgreSQL integrato — classificazione e policy per singola istruzione
  • instradamento delle chiamate API HTTP in uscita tramite servizi dichiarati (http_services) con regole per metodo e per percorso, gating di approvazione e applicazione host fail-closed
• Due modalità di output:
  • output shell leggibile per l'uomo
  • risposte JSON compatte per agenti/strumenti

---

Perché agentsh?

I flussi di lavoro degli agenti prima o poi eseguono codice arbitrario (pip install, make test, python script.py). I controlli tradizionali del tipo "chiedi approvazione prima di eseguire un comando" si fermano al confine dello strumento e non possono vedere cosa succede dentro quel comando.

agentsh applica la policy a runtime, quindi il lavoro nascosto svolto dai sottoprocessi rimane governato, registrato e (quando richiesto) approvato.

---

Blocchi significativi: deny → redirect (il superpotere dello "steering")

La maggior parte dei sistemi può negare un'azione. agentsh può anche reindirizzarla (redirect).

Questo significa che quando un agente prova l'approccio sbagliato (o aggiramenti brute-force), la policy può guidarlo verso la strada giusta sostituendo il comando e restituendo indicazioni — mantenendo l'agente sulla strada asfaltata e riducendo i tentativi sprecati.

Esempio: reindirizzare curl verso un wrapper auditato```yaml command_rules:

• name: redirect-curl commands: [curl, wget] decision: redirect message: "Downloads routed through audited fetch" redirect_to: command: agentsh-fetch args: ["--audit"]

**Esempio: reindirizza le scritture fuori dall'area di lavoro di nuovo al suo interno**```yaml
file_rules:
  - name: redirect-outside-writes
    paths: ["/home/**", "/tmp/**"]
    operations: [write, create]
    decision: redirect
    redirect_to: "/workspace/.scratch"
    message: "Writes outside workspace redirected to /workspace/.scratch"

L'agente vede un'operazione riuscita (non un errore), ma sei tu a controllare dove finiscono effettivamente le cose.

---

Containers + agentsh: meglio insieme

I container isolano la superficie host; agentsh aggiunge visibilità e policy di runtime all'interno del container.

• Audit per operazione (file, rete, comandi) mostra cosa è successo durante installazioni/build/test.
• Approvazioni e regole persistono tra shell di lunga durata e alberi di sottoprocessi, non solo il primo comando.
• Controlli a livello di percorso su workspace/cache/credenziali montati; i container non offrono nativamente questa granularità.
• Stesso comportamento su host e nei container, così CI e sviluppo locale vedono gli stessi esiti delle policy.

---

Avvio rapido

Installazione

macOS (Homebrew)```bash brew tap canyonroad/tap brew install --cask agentsh

Questa installa il bundle dell'app AgentSH con l'estensione di sistema ESF+NE. Dopo l'installazione ti verrà chiesto di approvare l'estensione di sistema in **Impostazioni di Sistema > Generali > Elementi di Accesso ed Estensioni**.

**Linux (da una Release di GitHub)**

Scarica il file `.deb`, `.rpm` o `.apk` per la tua piattaforma dalla [pagina delle release](https://github.com/erans/agentsh/releases).```bash
# Example for Debian/Ubuntu
sudo dpkg -i agentsh_<VERSION>_linux_amd64.deb

Dalla sorgente (Linux)```bash make build sudo install -m 0755 bin/agentsh bin/agentsh-shell-shim /usr/local/bin

**Dai sorgenti (macOS)**```bash
# ESF+NE mode (full enforcement — Alpha, requires Xcode 15+)
make build-macos-enterprise

Vedi Guida alla build di macOS per istruzioni dettagliate di build su macOS.

---

Esegui localmente```bash

Start the server (optional if using autostart)

./bin/agentsh server --config configs/server-config.yaml

Create a session and run a command (shell output)

SID=$(./bin/agentsh session create --workspace . --json | jq -r .id) ./bin/agentsh exec "$SID" -- ls -la

Structured output for agents

./bin/agentsh exec --output json --events summary "$SID" -- curl https://example.com

---

### Controlla cosa viene applicato

`agentsh detect` esamina l'host e riporta quali primitive di enforcement sono effettivamente disponibili — seccomp, Landlock, FUSE, eBPF, ptrace, cgroups — raggruppate in punteggi di protezione per dominio oltre alla modalità di sicurezza selezionata. Su host ristretti (Daytona, E2B, classe Firecracker) in cui il listener user-notify di seccomp non può essere installato, riporta la modalità che verrà *effettivamente* applicata anziché quella che il kernel supporta soltanto.```bash
agentsh detect              # human-readable protection report
agentsh detect config       # emit a config tuned for this host

Consulta Modalità di sicurezza per la matrice delle modalità e i parametri di regolazione.

---

Di' al tuo agente di usarlo (snippet AGENTS.md / CLAUDE.md)```md

Shell access

• Run commands via agentsh, not directly in bash/zsh.
• Use: agentsh exec $SID -- <your-command-here>
• For structured output: agentsh exec --output json --events summary $SID -- <your-command-here>
• Get session ID first: SID=$(agentsh session create --workspace . --json | jq -r .id)

---

### Avvio automatico (nessun passaggio manuale del daemon)

Non è **necessario** avviare `agentsh server` manualmente.