Gemini CLI Sandbox-Modus: Aktivierung, Backends, YOLO-Sicherheit
Der bebilderte, schnörkellose Guide zur Sandbox von Gemini CLI: mit -s starten, dauerhaft aktivieren, das richtige Backend fürs Betriebssystem wählen und dem YOLO-Modus ein Sicherheitsnetz geben.
Kurz zusammengefasst
- gemini -s ausführen, und die ganze Session — Shell-Befehle, Dateiänderungen, Netzwerkaufrufe — läuft in einer isolierten Sandbox; im Footer erscheint eine Sandbox-Anzeige, sodass du sie aktiv siehst.
- Drei Aktivierungswege, in dieser Reihenfolge ausgewertet: das Flag -s / --sandbox, die Umgebungsvariable GEMINI_SANDBOX, dann "sandbox": true im tools-Objekt der settings.json.
- Die Backends sind OS-abhängig: macOS nutzt Seatbelt-Profile (Standard permissive-open), Linux gVisor runsc für die stärkste Isolation, sonst Docker- oder Podman-Container.
- Der YOLO-Modus (--yolo) überspringt jede Berechtigungsabfrage — kombinier ihn mit der Sandbox. v0.61.0 (23. Sept. 2026) härtete die Dateisystemgrenzen der Sandbox und isolierte den Runtime-Zustand.
Gemini CLI Essentials – Full Course (sandboxing chapter)
Kanal: freeCodeCamp.org3:49:40
Gemini CLI: Everything You Need To Know (Full Tutorial)
Kanal: lustoykov42:54
Sandboxing in Gemini CLI — official documentation
Doku: google-gemini/gemini-cli (GitHub)
Die Screenshots stammen aus dem Sandbox-Kapitel des freeCodeCamp-Kurses; Flag-Namen, Einstellungen und Profile wurden gegen die offizielle Sandbox-Dokumentation und die v0.61.0-Release-Notes geprüft.
Screenshot-Credits: freeCodeCamp.org und lustoykov — Aufnahmen als visuelle Referenz mit Quellenangabe genutzt; alle Schritttexte sind von uns.
Gemini CLI Schritt für Schritt sandboxen
Erste Sandbox-Session starten
- 1
Wisse, was die Sandbox wirklich isoliert
Die Sandbox hält die Operationen vom Host-System fern, mit denen ein KI-Agent gefährlich wird — Shell-Befehle, Datei-Schreibvorgänge, Netzwerkaufrufe. Gemini CLI v0.61.0 (23. September 2026) härtete die Dateisystemgrenzen der Sandbox und isolierte den Runtime-Zustand, wodurch indirekte Prompt-Injection-Wege über Build-Dateien und nicht vertrauenswürdige Flags geschlossen wurden.
Wo die Sandbox sitzt: eine Isolationsbibliothek auf OS-Ebene, je Plattform unterschiedlich.Ansehen bei 140:00 - 2
Direkt per Flag in die Sandbox starten
Der schnellste Weg ist das Kommandozeilen-Flag: führe gemini -s aus (Langform --sandbox). Der erste Start kann eine Minute dauern, weil das Sandbox-Image womöglich erst gezogen wird. Für Einmal-Läufe kombinierst du es mit einem Prompt: gemini -s -p "analyze the code structure".
Flag an, Footer-Anzeige an — der Zwei-Sekunden-Gesundheitscheck.Ansehen bei 140:50 - 3
Die drei Aktivierungswege kennen — und welcher gewinnt
Gemini CLI wertet die Sandbox-Einstellung nach Priorität aus: zuerst das Flag -s / --sandbox, dann die Umgebungsvariable GEMINI_SANDBOX (true, docker, podman, sandbox-exec, runsc oder lxc), dann der Eintrag "sandbox" im tools-Objekt deiner settings.json.
Die offizielle Doku listet alle drei Wege in Prioritätsreihenfolge.Ansehen bei 145:45 - 4
Im Footer bestätigen, dass die Session sandboxed ist
Sobald die CLI läuft, zeigt der Footer eine Sandbox-Anzeige mit der Version der Sandbox-Komponente, direkt neben der Modellauswahl. Keine Anzeige, keine Sandbox — geh zurück und prüfe, welches Flag oder welche Einstellung sie deiner Meinung nach aktivieren sollte.
Eine echte Sandbox-Session: die Anzeige sitzt neben Auto (Gemini 3).Ansehen bei 146:40
Das richtige Backend für dein OS wählen
- 5
Unter macOS den eingebauten Seatbelt nutzen
macOS braucht keine Container: Gemini CLI wickelt den Prozess in Seatbelt (sandbox-exec). Das Standardprofil permissive-open beschränkt Schreibvorgänge auf das Projektverzeichnis, während Lesen und Netz offen bleiben. Härter wird's mit der Umgebungsvariable SEATBELT_PROFILE — permissive-proxied, restrictive-open, restrictive-proxied, strict-open oder strict-proxied.
- 6
Unter Linux oder WSL2: gVisor runsc
Googles gVisor — die runsc-Runtime — bietet die stärkste verfügbare Isolation: Container laufen auf einem Userspace-Kernel, der jeden Systemaufruf abfängt. Explizit wählen mit GEMINI_SANDBOX=runsc oder "sandbox": "runsc" (wird nie automatisch erkannt), und Gemini CLI startet docker run --runtime=runsc für dich.
Die Doku positioniert runsc als stärkstes, Linux-exklusives Backend.Ansehen bei 141:20 - 7
Die runsc-Runtime installieren
Unter Ubuntu — nativ oder in WSL2 — holt ein apt-Befehl die gVisor-Runtime: sudo apt get install runsc. Docker muss ebenfalls installiert und laufen, denn Gemini CLI treibt runsc als Docker-Runtime an, nicht als Standalone-Werkzeug.
Eingabe des Install-Befehls in einem WSL2-Ubuntu-Terminal.Ansehen bei 143:35 - 8
Prüfen, ob die Installation sitzt
apt entpackt runsc direkt aus dem Security-Updates-Repo von Ubuntu — kein zusätzliches PPA. Ohne diesen Schritt schlägt ein späteres gemini -s unter Linux fehl oder fällt stillschweigend auf das Container-Backend zurück — prüfe das Paket also vor dem ersten sandboxed Run.
apt schließt das Entpacken von runsc auf Ubuntu 24.04 ab.Ansehen bei 144:15 - 9
Lieber Container? Docker oder Podman auf jedem OS
Containerbasiertes Sandboxing läuft überall dort, wo Docker oder Podman läuft — und beides muss vor dem Start installiert und gestartet sein: führe einmal docker aus, um zu sehen, dass die CLI antwortet. Standardmäßig nutzt die Sandbox das Image ghcr.io/google/gemini-cli:latest und mountet dein Arbeitsverzeichnis unter exakt demselben absoluten Pfad im Container.
Einmal docker ausführen, um zu sehen, dass die Engine antwortet.Ansehen bei 145:30
YOLO-Modus ohne Kaltschweißigkeit fahren
- 10
Sandbox und YOLO-Modus kombinieren
gemini --yolo (Kurzform von --approval-mode=yolo) überspringt auf riskante Weise jede Berechtigungsabfrage — genau das, was autonome Läufe brauchen, und genau dafür ist eine Sandbox da. Starte YOLO-Sessions mit dem Sandbox-Flag, damit die übersprungenen Abfragen weiterhin in der isolierten Umgebung landen.
YOLO-Modus auf einer Folie: keine Unterbrechungen, alle Rechte sofort frei.Ansehen bei 148:20 - 11
Verifizieren, dass autonome Läufe sandboxed blieben
Während YOLO-Sessions wechselt der Footer auf ein blaues YOLO-Mode-Badge — dein Hinweis, dass Einfragen übersprungen werden. Nach dem Lauf zeigt die /stats-Interaktionszusammenfassung, welche Tools feuerten, und die Sandbox-Anzeige bleibt der Beweis, dass die Arbeit im Kasten stattfand.
Das YOLO-Mode-Badge im Footer einer beendeten autonomen Session.Ansehen bei 147:40
Eigene Sandbox-Images und Container-Flags
Das Standard-Container-Image reicht für allgemeines Coding. Wenn dein Projekt eine eigene Toolchain braucht — oder deine Container-Umgebung sich querstellt — hat Gemini CLI vier Stellschrauben.
- 1Beliebiges Image angeben: GEMINI_SANDBOX_IMAGE setzen oder die Objektform in der settings.json — "sandbox": "command": "docker", "image": "..." (a JSON object). Jedes Docker-/Podman-Image mit bash funktioniert.
- 2Selbst bauen: eine .gemini/sandbox.Dockerfile ins Projektroot legen und mit BUILD_SANDBOX=1 starten — Gemini CLI baut das Image automatisch. Automatische Builds gehen nur beim Ausführen aus dem Quellcode; bei npm-Installationen referenziere ein vorgebautes Image.
- 3Container-Befehl justieren: SANDBOX_FLAGS injiziert zusätzliche docker/podman-Flags — etwa behebt export SANDBOX_FLAGS="--security-opt label=disable" SELinux-Volume-Mount-Ablehnungen bei Podman.
- 4Dateieigentümer unter Linux fixen: Die Sandbox mappt Benutzerrechte automatisch, aber SANDBOX_SET_UID_GID=true erzwingt Host-UID/GID, wenn erzeugte Dateien dem falschen Nutzer gehören.
Du betreibst Gemini CLI selbst in einem Container und willst darin sandboxen? Mounte /var/run/docker.sock, damit die CLI Geschwister-Container über den Host-Daemon erzeugen kann, und gleiche den Workspace-Pfad exakt an den absoluten Host-Pfad an — die Volume-Mounts löst der Host-Daemon auf, nicht der Container.
Fehlersuche: Fehler, Dateizugriff, Deaktivieren
Die meisten Sandbox-Probleme laufen auf fünf Muster hinaus. Zuerst immer mit Debug-Ausgabe reproduzieren: DEBUG=1 gemini -s -p "your prompt".
- 1"Operation not permitted" — der Befehl braucht Zugriff außerhalb der Sandbox. Wechsle zu einem großzügigeren Profil (macOS: SEATBELT_PROFILE) oder ergänze die nötigen Mounts.
- 2Fehlende Befehle in der Sandbox — backe deine Tools in ein eigenes Image oder installiere sie via sandbox.bashrc. Denk dran: BUILD_SANDBOX-Automatik ist nur für Quellcode-Checkouts.
- 3Netzwerkfehler — prüfe, ob das aktive Profil Netzwerk überhaupt erlaubt, und kontrolliere die Proxy-Konfiguration; -proxied-Profile leiten Verkehr über den Sandbox-Proxy.
- 4Dateien unter Linux mit falschem Eigentümer — SANDBOX_SET_UID_GID umschalten (true erzwingt Host-UID/GID, false deaktiviert das Mapping).
- 5Windows hat Dateien mit Low Integrity hinterlassen — die native Sandbox markiert schreibbare Pfade per icacls; zurücksetzen mit icacls "C:\path\to\dir" /setintegritylevel Medium.
Was die Sandbox erreichen kann, fragst du am besten die CLI selbst ab: gemini -s -p "run shell command: env | grep SANDBOX" listet die Sandbox-Umgebungsvariablen, mount | grep workspace zeigt die Mounts. Für Dateien braucht es keinen Export — Container-Sandboxes mounten dein Projekt unter demselben absoluten Pfad, Änderungen landen direkt in deinem Ordner. Zum Deaktivieren: Flag -s weglassen, GEMINI_SANDBOX entfernen oder den Eintrag "sandbox" aus der settings.json löschen; Tool-Level-Sandboxing hat einen eigenen Schalter, "security": "toolSandboxing": false (Neustart nötig).