agentsh

Hinweis für macOS: Die native macOS-Durchsetzung über ESF (Endpoint Security Framework) + NE (Network Extension) befindet sich im Alpha-Stadium. Sie funktioniert Ende-zu-Ende — Datei-, Prozess- und Netzwerkereignisse fließen über die Systemerweiterung in die Go-Policy-Engine — aber erwarten Sie raue Kanten und bahnbrechende Änderungen zwischen Releases. Für den Produktionseinsatz empfehlen wir derzeit Linux.

Hinweis für Windows: Wir arbeiten daran, die Minifilter-Treiber signieren zu lassen. Bis dahin ist nur der Windows-WSL2-Modus für den Produktionseinsatz vollständig unterstützt.

Sicherer, richtliniengesteuerter Ausführungs-Gateway für KI-Agenten.

agentsh sitzt unter Ihrem Agenten/Tooling — es erfasst Datei-, Netzwerk-, Prozess- und Signal-Aktivitäten (einschließlich Subprozess-Bäume), setzt die von Ihnen definierte Richtlinie durch und emittiert strukturierte Audit-Ereignisse.

Plattform-Hinweis: Linux bietet vollständige Durchsetzung (100 % Sicherheitsbewertung). macOS ESF+NE (90 % Bewertung) befindet sich im Alpha-Stadium — funktional, aber nicht produktionsreif. Windows WSL2 bietet vollständige, Linux-äquivalente Durchsetzung (100 % Bewertung); natives Windows über Minifilter-Treiber + AppContainer (85 % Bewertung) wartet auf die Treibersignierung. Siehe Plattform-Vergleichsmatrix für Details.

---

Was ist agentsh?

• Drop-in-Shell/Exec-Endpunkt, der jeden Befehl (und seine Subprozesse) in auditierbare Ereignisse verwandelt.
• Richtlinien-Engine pro Operation: allow, deny, approve (menschliche Freigabe), soft_delete oder redirect.
• Volle I/O-Sichtbarkeit:
  • Datei öffnen/lesen/schreiben/löschen
  • Netzwerkverbindung + DNS
  • Prozessstart/-ende
  • PTY-Aktivität
  • LLM-API-Anfragen mit DLP und Nutzungsverfolgung
  • Postgres-Familie-Datenbankverkehr über deklarierte db_services
  • Signal senden/blockieren (Linux durchgesetzt, macOS/Windows Audit)
  • Datenbankabfragen über den eingebetteten PostgreSQL-Proxy — Klassifizierung und Richtlinie pro Anweisung
  • Ausgehende HTTP-API-Aufrufe über deklarierte Dienste (http_services) mit Regeln pro Methode, pro Pfad, Freigabe-Gating und Fail-Closed-Host-Durchsetzung
• Zwei Ausgabemodi:
  • menschenfreundliche Shell-Ausgabe
  • kompakte JSON-Antworten für Agenten/Werkzeuge

---

Warum agentsh?

Agent-Workflows führen irgendwann beliebigen Code aus (pip install, make test, python script.py). Traditionelle „Vor der Befehlsausführung um Genehmigung fragen"-Kontrollen enden an der Tool-Grenze und können nicht sehen, was innerhalb dieses Befehls passiert.

agentsh setzt Richtlinien zur Laufzeit durch, sodass versteckte Arbeit von Subprozessen weiterhin gesteuert, protokolliert und (falls erforderlich) genehmigt wird.

---

Sinnvolle Blockierungen: deny → redirect (die „Steuerungs"-Superkraft)

Die meisten Systeme können eine Aktion verweigern. agentsh kann sie auch umleiten (redirect).

Das bedeutet: Wenn ein Agent den falschen Ansatz versucht (oder Brute-Force-Workarounds), kann die Richtlinie ihn auf den richtigen Pfad lenken, indem sie den Befehl austauscht und Anleitung zurückgibt — so bleibt der Agent auf der befestigten Straße und verschwendete Wiederholungsversuche werden reduziert.

Beispiel: curl zu einem auditierten Wrapper umleiten```yaml command_rules:

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

**Beispiel: Schreibvorgänge außerhalb des Arbeitsbereichs zurück nach innen umleiten**```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"

Der Agent sieht eine erfolgreiche Operation (keinen Fehler), aber du kontrollierst, wohin die Dinge tatsächlich landen.

---

Container + agentsh: besser zusammen

Container isolieren die Host-Oberfläche; agentsh fügt Laufzeitsichtbarkeit und Richtlinien innerhalb des Containers hinzu.

• Pro-Operation-Audit (Dateien, Netzwerk, Befehle) zeigt, was während Installationen/Builds/Tests passiert ist.
• Genehmigungen und Regeln bleiben über langlebige Shells und Subprozess-Bäume hinweg bestehen – nicht nur für den ersten Befehl.
• Kontrollen auf Pfadebene für gemountete Workspaces/Caches/Credentials; Container bieten diese Granularität nicht nativ.
• Gleiches Verhalten auf dem Host und in Containern, sodass CI und lokale Entwicklung dieselben Richtlinienergebnisse sehen.

---

Schnellstart

Installation

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

Dies installiert das AgentSH-App-Bundle mit der ESF+NE-Systemerweiterung. Nach der Installation werden Sie aufgefordert, die Systemerweiterung in **Systemeinstellungen > Allgemein > Anmeldeobjekte & Erweiterungen** zu genehmigen.

**Linux (aus einem GitHub-Release)**

Laden Sie die `.deb`, `.rpm` oder `.apk` für Ihre Plattform von der [Releases-Seite](https://github.com/erans/agentsh/releases) herunter.```bash
# Example for Debian/Ubuntu
sudo dpkg -i agentsh_<VERSION>_linux_amd64.deb

Aus dem Quellcode (Linux)```bash make build sudo install -m 0755 bin/agentsh bin/agentsh-shell-shim /usr/local/bin

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

Siehe macOS-Build-Anleitung für detaillierte macOS-Build-Anweisungen.

---

Lokal ausführen```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

### Prüfen, was durchgesetzt wird

`agentsh detect` untersucht den Host und meldet, welche Durchsetzungs-Primitiven tatsächlich verfügbar sind — seccomp, Landlock, FUSE, eBPF, ptrace, cgroups — gruppiert in bereichsspezifische Schutzwerte sowie den ausgewählten Sicherheitsmodus. Auf eingeschränkten Hosts (Daytona, E2B, Firecracker-Klasse), auf denen der seccomp-user-notify-Listener nicht installiert werden kann, meldet es den Modus, der *tatsächlich* durchsetzt, statt nur das, was der Kernel lediglich unterstützt.```bash
agentsh detect              # human-readable protection report
agentsh detect config       # emit a config tuned for this host

Siehe Sicherheitsmodi für die Modusmatrix und die Stellschrauben.

---

Sagen Sie Ihrem Agenten, er soll es verwenden (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)

---

### Autostart (ohne manuellen Daemon-Schritt)

Du musst `agentsh server` **nicht** selbst starten.

* Der erste `agentsh exec`-Aufruf (oder jede geshimte `/bin/sh`/`/bin/bash`) startet automatisch einen lokalen Server mit `configs/server-config.yaml` (bzw. `AGENTSH_CONFIG`, falls gesetzt).
* Dieser Server hält die FUSE-Ebene und die Policy-Engine für die gesamte Sitzungsdauer am Leben; nachfolgende Befehle verwenden ihn erneut.
* Setze `AGENTSH_NO_AUTO=1`, wenn du den Server-Lebenszyklus manuell verwalten möchtest.

---