Diese Seite ist eine Übersetzung der englischen Dokumentation. Befehle, Bezeichner und Beispiele bleiben unverändert. Runtime 7.24.4 · SDK 2.6.7. Englische Fassung

Sandbox-Modus

Status: Aktiv Geltungsbereich: aktueller Stand Zuletzt geprüft: 2026-08-23 Verantwortlich: ax-code runtime

AX Code enthält eine eingebaute Ausführungssandbox, die einschränken kann, was der KI-Agent auf Ihrem System tut. Standardmäßig startet AX Code mit vollem Zugriff und ausgeschalteter Sandbox, sodass Schreibzugriffe auf das Dateisystem und der Netzwerkzugriff unbeschränkt sind. Aktivieren Sie workspace-write oder read-only, bevor Sie mit nicht vertrauenswürdigen Repositories arbeiten oder unbeaufsichtigte Aufgaben ausführen.

Sicherheitswarnung: full-access ist keine Sicherheitsgrenze. Der Agent kann Dateien außerhalb des Arbeitsbereichs ändern, .git/ und .ax-code/ schreiben, uneingeschränkte Shell-Befehle ausführen und auf das Netzwerk zugreifen.

Schnellstart

Schalten Sie die Sandbox in der TUI um:

• Geben Sie /sandbox in die Eingabe ein, oder
• Drücken Sie Ctrl+P und suchen Sie nach „Sandbox“

Die Statusleiste zeigt den aktuellen Zustand:

• Sandbox an (grün) — der Agent bleibt auf den Arbeitsbereich beschränkt
• Sandbox aus (rot) — keine Einschränkungen

Die Einstellung bleibt über Sitzungen hinweg in ax-code.json erhalten.

Was sich ändert

Konfiguration

Maßgebliche Quelle

Diese Seite fasst das Verhalten für Benutzer zusammen. Wenn sich das Verhalten ändert, prüfen Sie die Dokumentation anhand dieser Stellen:

• packages/ax-code/src/isolation/index.ts für die Auflösung des Modus, geschützte Pfade, Netzprüfungen, Schreibprüfungen, Bash-Prüfungen und IsolationDeniedError.
• packages/ax-code/src/config/schema.ts für die Form der Konfiguration, Voreinstellungen und Beschreibungen.
• packages/ax-code/src/server/routes/isolation.ts für das Umschaltverhalten zur Laufzeit und das Speichern.
• packages/ax-code/test/isolation/isolation.test.ts und packages/ax-code/test/tool/bash.test.ts für das erwartete Durchsetzungsverhalten.

Halten Sie doppelte Aussagen in der README im Wurzelverzeichnis kurz und verlinken Sie für Einzelheiten hierher.

Umschalten in der TUI

Verwenden Sie /sandbox oder die Befehlspalette (Ctrl+P → „Sandbox ein- oder ausschalten“). Die Änderung wirkt sofort und wird in ax-code.json Ihres Projekts gespeichert.

CLI-Option

ax-code --sandbox workspace-write   # sandbox on
ax-code --sandbox full-access       # sandbox off
ax-code --sandbox read-only         # strictest: blocks all mutations

Umgebungsvariable

AX_CODE_ISOLATION_MODE=workspace-write ax-code

Konfigurationsdatei

In ax-code.json:

{
  "isolation": {
    "mode": "workspace-write",
    "network": false
  }
}

Vorrang

CLI-Option > Umgebungsvariable > Konfigurationsdatei > Voreinstellung (full-access)

Wenn eine Überschreibung per CLI oder Umgebung aktiv ist, zeigt die TUI diesen wirksamen Modus. Ein Umschalten mit /sandbox kann die Projektvoreinstellung speichern. Die Überschreibung mit höherem Vorrang bleibt aktiv, bis sie entfernt wird, normalerweise beim Neustart.

Isolationsmodi

Geschützte Pfade

Im Modus workspace-write sind diese Pfade immer schreibgeschützt:

• .git/ — verhindert eine versehentliche Beschädigung des Git-Zustands
• .ax-code/ — verhindert die Manipulation von Konfiguration oder Plugin

Ergänzen Sie eigene geschützte Pfade in der Konfiguration:

{
  "isolation": {
    "mode": "workspace-write",
    "protected": ["secrets", "credentials"]
  }
}

Netzwerkzugriff

Das Netzwerk ist in den Modi workspace-write und read-only standardmäßig deaktiviert. Betroffene Werkzeuge:

• webfetch — blockiert
• websearch — blockiert
• codesearch — blockiert
• bash — Clients nur für das Netzwerk (curl, wget, nc/ncat/netcat, telnet, ftp, tftp, scp, sftp, dig, nslookup, host) sind blockiert

Einschränkung: Die Netzwerksperre in bash liegt auf der Anwendungsschicht und erfasst die oben genannten Clients, die nur das Netzwerk ansprechen. Sie fängt Werkzeuge mit doppeltem Zweck, die auch offline arbeiten (git, npm/pnpm/yarn, pip, go, Sprachinterpreter wie python/node), nicht ab, weil sich ihre Offline-Aufrufe statisch nicht unterscheiden lassen und eine Sperre übliche Arbeitsabläufe unterbrechen würde. Eine echte, vollständige Netzwerkisolation verlangt Steuerungen auf Betriebssystemebene. Diese Sandbox stellt sie nicht bereit. Trifft der Agent auf einen abgelehnten Client, fordert er eine einmalige Eskalation an.

So erlauben Sie das Netzwerk und behalten die Schreibbeschränkungen:

{
  "isolation": {
    "mode": "workspace-write",
    "network": true
  }
}

Isolations-Backend (Anwendung gegenüber Betriebssystem)

macOS: Seatbelt-Profile über sandbox-exec (Schreiben beschränkt auf Arbeitsbereich und Worktree, Netzwerk verweigert bei network: false).
Linux: bubblewrap (bwrap), sofern installiert (--unshare-net bei deaktiviertem Netzwerk, Arbeitsbereich per Bind-Mount lesend und schreibend).
Windows: heute nur die Anwendungsschicht.

{
  "isolation": {
    "mode": "workspace-write",
    "network": false,
    "backend": "auto"
  }
}

Siehe SECURITY.md zum Bedrohungsmodell.

Durch das Repository gesteuerte Berechtigungen und Hooks

Projektdateien gelten standardmäßig als nicht vertrauenswürdig. Berechtigungsregeln in ax-code.json, .ax-code/policy.json sowie Definitionen von Projektagent oder Modus dürfen den Zugriff mit deny enger fassen, doch vom Repository gesteuerte Freigaben allow/ask werden ignoriert. Projektbefehle können die Shell-Expansion nicht aktivieren. .ax-code/hooks.json, .ax-code/plugin/ und vom Projekt konfigurierte Plugins werden nicht ausgeführt.

Nicht vertrauenswürdige Projektkonfiguration kann außerdem keine eigene Shell, kein ausführbares LSP und keinen Formatierer, kein Anbieterpaket und keinen API-Endpunkt, keine Umgebungsvariablen für Anbieterzugangsdaten, keine externe Skill-Quelle und keinen Anweisungspfad außerhalb des Worktrees wählen. Sichere relative Anweisungspfade und nicht ausführbare eingebaute Überschreibungen bleiben verfügbar. MCP-Server nutzen einen getrennten Genehmigungsablauf mit Fingerabdruck, beschrieben in MCP-Integrationen.

Nach der Prüfung der vom Repository gesteuerten Konfiguration können Sie außerhalb des Repositories für den aktuellen Prozess zustimmen:

AX_CODE_TRUST_PROJECT_CONFIG=1 ax-code

Der Schalter nur über die Umgebung verhindert, dass ein Checkout sich selbst als vertrauenswürdig erklärt.

So funktioniert die Durchsetzung

Die Durchsetzung der Sandbox liegt immer auf der Anwendungsschicht und wird bei jedem Werkzeugaufruf geprüft. Wenn backend os oder auto ist und die Plattform das unterstützt, wird Bash zusätzlich in eine Kernel-Sandbox gehüllt.

Verletzt ein Werkzeug die Isolation, löst es ein IsolationDeniedError mit einer klaren Meldung aus, die erklärt, was blockiert wurde und warum.