agentsh

Note macOS : La mise en œuvre native macOS via ESF (Endpoint Security Framework) + NE (Network Extension) est en version Alpha. Elle fonctionne de bout en bout — les événements de fichiers, de processus et de réseau transitent par l'extension système vers le moteur de politique Go — mais attendez-vous à des aspérités et des changements cassants entre les versions. Pour une utilisation en production aujourd'hui, nous recommandons Linux.

Note Windows : Nous travaillons à faire signer les pilotes minifilter. D'ici là, seul le mode Windows WSL2 est entièrement pris en charge pour une utilisation en production.

Passerelle d'exécution sécurisée et supervisée par des politiques pour les agents IA.

agentsh se place sous votre agent/outillage — interceptant les activités fichier, réseau, processus et signal (y compris les arborescences de sous-processus), appliquant la politique que vous définissez et émettant des événements d'audit structurés.

Note plateforme : Linux offre une application complète (score de sécurité 100 %). macOS ESF+NE (score 90 %) est en Alpha — fonctionnel mais pas prêt pour la production. Windows WSL2 offre une application équivalente à Linux (score 100 %) ; le Windows natif via pilote minifilter + AppContainer (score 85 %) est en attente de signature de pilote. Voir la Matrice de comparaison des plateformes pour plus de détails.

---

Qu'est-ce que agentsh ?

• Point de terminaison shell/exec enfichable qui transforme chaque commande (et ses sous-processus) en événements audités.
• Moteur de politique par opération : allow, deny, approve (approbation humaine), soft_delete ou redirect.
• Visibilité complète des E/S :
  • ouverture/lecture/écriture/suppression de fichiers
  • connexion réseau + DNS
  • démarrage/arrêt de processus
  • activité PTY
  • requêtes API LLM avec DLP et suivi d'utilisation
  • trafic de base de données de type Postgres via les db_services déclarées
  • envoi/blocage de signaux (appliqué sur Linux, audit sur macOS/Windows)
  • requêtes de base de données via le proxy PostgreSQL intégré — classification par instruction et politique
  • Acheminer les appels API HTTP sortants via les services déclarés (http_services) avec des règles par méthode, par chemin, contrôle d'approbation et application hôte en échec-fermé
• Deux modes de sortie :
  • sortie shell lisible par l'humain
  • réponses JSON compactes pour agents/outils

---

Pourquoi agentsh ?

Les workflows d'agents exécutent finalement du code arbitraire (pip install, make test, python script.py). Les contrôles traditionnels « demander une approbation avant d'exécuter une commande » s'arrêtent à la limite de l'outil et ne peuvent pas voir ce qui se passe à l'intérieur de cette commande.

agentsh applique la politique à l'exécution, de sorte que le travail caché effectué par les sous-processus est toujours régi, journalisé et (le cas échéant) approuvé.

---

Blocs significatifs : deny → redirect (le superpouvoir d'« orientation »)

La plupart des systèmes peuvent refuser une action. agentsh peut aussi la rediriger.

Cela signifie que lorsqu'un agent tente la mauvaise approche (ou des solutions de contournement par force brute), la politique peut l'orienter vers le bon chemin en échangeant la commande et en renvoyant des instructions — maintenant l'agent sur la voie pavée et réduisant les tentatives inutiles.

Exemple : rediriger curl vers un wrapper audité```yaml command_rules:

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

**Exemple : rediriger les écritures en dehors de l'espace de travail vers l'intérieur**```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'agent voit une opération réussie (pas une erreur), mais vous contrôlez où les choses aboutissent réellement.

---

Conteneurs + agentsh : mieux ensemble

Les conteneurs isolent la surface de l'hôte ; agentsh ajoute une visibilité et une politique d'exécution dans le conteneur.

• Audit par opération (fichiers, réseau, commandes) montre ce qui s'est passé pendant les installations/constructions/tests.
• Les approbations et les règles persistent à travers les shells de longue durée et les arbres de sous-processus — pas seulement la première commande.
• Contrôles au niveau du chemin sur les espaces de travail montés/caches/credentials ; les conteneurs ne fournissent pas nativement cette granularité.
• Même comportement sur l'hôte et dans les conteneurs, donc CI et dev local voient les mêmes résultats de politique.

---

Démarrage rapide

Installation

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

Cela installe le bundle d'applications AgentSH avec l'extension système ESF+NE. Après l'installation, il vous sera demandé d'approuver l'extension système dans **Réglages système > Général > Éléments de connexion et extensions**.

**Linux (à partir d'une version GitHub)**

Téléchargez le `.deb`, `.rpm` ou `.apk` pour votre plateforme depuis la [page des versions](https://github.com/erans/agentsh/releases).```bash
# Example for Debian/Ubuntu
sudo dpkg -i agentsh_<VERSION>_linux_amd64.deb

Depuis les sources (Linux)```bash make build sudo install -m 0755 bin/agentsh bin/agentsh-shell-shim /usr/local/bin

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

Voir Guide de construction macOS pour des instructions détaillées de construction sur macOS.

---

Exécution locale```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

---

### Vérifier ce qui est appliqué

`agentsh detect` sonde l'hôte et rapporte quelles primitives d'application sont réellement disponibles — seccomp, Landlock, FUSE, eBPF, ptrace, cgroups — regroupées en scores de protection par domaine ainsi que le mode de sécurité sélectionné. Sur les hôtes restreints (Daytona, E2B, classe Firecracker) où l'écouteur seccomp user-notify ne peut pas s'installer, il rapporte le mode qui sera *réellement* appliqué plutôt que ce que le noyau supporte simplement.```bash
agentsh detect              # human-readable protection report
agentsh detect config       # emit a config tuned for this host

Voir Modes de sécurité pour la matrice des modes et les réglages fins.

---

Dites à votre agent de l'utiliser (AGENTS.md / CLAUDE.md snippet)```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)

---

### Démarrage automatique (aucune étape manuelle du démon)

Vous n'avez **pas** besoin de démarrer `agentsh server` vous-même.