Zerobox Python SDK

Python SDK für zerobox. Führe jeden Befehl in einer Sandbox mit Datei-, Netzwerk- und Zugangsdaten-Kontrollen aus.

pip install zerobox

Die Installation des Wheels legt die zerobox-CLI in das bin/-Verzeichnis Ihrer Umgebung und stellt ein Python-SDK bereit.

Informationen zur CLI-Nutzung, zu Secrets-Konzepten, zur vollständigen Flag-Referenz, zu Leistungszahlen und zur Plattformunterstützung finden Sie in der Haupt-README.

Schnellstart

from zerobox import Sandbox

sandbox = Sandbox.create({"allow_write": ["/tmp"]})
print(sandbox.sh("echo hello").text())

Befehle

Es gibt drei Möglichkeiten, einen Befehl auszuführen. Jede gibt ein ShellCommand zurück, das Sie mit .text(), .json() oder .output() abschließen.

Shell

name = "world"
sandbox.sh(f"echo hello {name}").text()

Inline-Python

data = sandbox.py("import json; print(json.dumps({'sum': 1 + 2}))").json()

Expliziter Befehl + Argumente

sandbox.exec("python3", ["-c", "print('hi')"]).text()

Ergebnisse

Methode	Bei Erfolg	Bei Exit ungleich null
.text()	Gibt stdout als String zurück	Löst SandboxCommandError aus
.json()	Parst stdout als JSON	Löst SandboxCommandError aus
.output()	Gibt CommandOutput(code, stdout, stderr) zurück	Gibt dieselbe Struktur zurück, löst nie eine Ausnahme aus

data = sandbox.sh("cat data.json").json()
result = sandbox.sh("exit 42").output()
# CommandOutput(code=42, stdout='', stderr='')

Asynchrone API

Verwenden Sie AsyncSandbox in asynchronen Anwendungen, damit das Warten auf den in der Sandbox ausgeführten Unterprozess die Ereignisschleife nicht blockiert. Die Befehlsstruktur ist dieselbe wie bei Sandbox, aber Erstellung und Terminatoren werden mit await abgewartet.

from zerobox import AsyncSandbox

sandbox = await AsyncSandbox.create({"allow_write": ["/tmp"]})

text = await sandbox.sh("echo hello").text()
data = await sandbox.sh("printf '{\"ok\": true}'").json()
result = await sandbox.exec("python3", ["-c", "print('hi')"]).output()

Asynchrone Befehle akzeptieren dieselbe timeout-Option:

import subprocess

try:
    await sandbox.sh("sleep 60").text(timeout=1.0)
except subprocess.TimeoutExpired:
    print("cancelled")

Fehlerbehandlung

Ein Exit-Code ungleich null löst SandboxCommandError aus:

from zerobox import Sandbox, SandboxCommandError

sandbox = Sandbox.create()
try:
    sandbox.sh("exit 1").text()
except SandboxCommandError as e:
    print(e.code, e.stderr)

Secrets

Übergeben Sie API-Schlüssel, die der sandboxed Prozess nie sieht. Der Proxy ersetzt den echten Wert nur für genehmigte Hosts.

import os
from zerobox import Sandbox

sandbox = Sandbox.create({
    "secrets": {
        "OPENAI_API_KEY": {
            "value": os.environ["OPENAI_API_KEY"],
            "hosts": ["api.openai.com"],
        },
        "GITHUB_TOKEN": {
            "value": os.environ["GITHUB_TOKEN"],
            "hosts": ["api.github.com"],
        },
    },
})

sandbox.sh('curl -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/v1/models').text()

Informationen zur Funktionsweise der Platzhalter-Ersetzung finden Sie in der Haupt-README.

Snapshots

Dateisystemänderungen aufzeichnen und automatisch zurücksetzen:

sandbox = Sandbox.create({
    "allow_write": ["."],
    "restore": True,
})
sandbox.sh("npm install").text()

Aufzeichnung ohne Rollback:

sandbox = Sandbox.create({
    "allow_write": ["."],
    "snapshot": True,
    "snapshot_exclude": ["node_modules"],
})
sandbox.sh("npm install").text()

Abbruch

Übergeben Sie einem beliebigen Terminator einen timeout (Sekunden):

import subprocess
try:
    sandbox.sh("sleep 60").text(timeout=1.0)
except subprocess.TimeoutExpired:
    print("cancelled")

Umgebungsvariablen

sandbox = Sandbox.create({
    "env": {"NODE_ENV": "production"},
    "allow_env": ["PATH", "HOME"],
    "deny_env": ["AWS_SECRET_ACCESS_KEY"],
})

Siehe die Haupt-README für die standardmäßig vererbten Einstellungen und die CLI-Äquivalente.

Optionen

Sandbox.create(options) akzeptiert eine SandboxOptions-Dataclass oder ein einfaches Dict. Alle Felder sind optional.

Feld	Typ	Beschreibung
profile	str | list[str]	Benannte(s) Profil(e). Eine Liste wird von links nach rechts zusammengeführt. Standard "workspace".
allow_read / deny_read	list[str]	Lesbare / blockierte Pfade.
allow_write / deny_write	list[str]	Beschreibbare / blockierte Pfade.
allow_net	bool | list[str]	True erlaubt alles. Eine Liste beschränkt auf diese Domains.
deny_net	list[str]	Blockierte Domains.
allow_all	bool	Voller Dateisystem- und Netzwerkzugriff.
no_sandbox	bool	Deaktiviert die Sandbox vollständig.
strict_sandbox	bool	Schlägt fehl, statt auf schwächere Isolation zurückzufallen.
cwd	str	Arbeitsverzeichnis.
env	dict[str, str]	Explizite Umgebungsvariablen.
allow_env	bool | list[str]	Umgebungsvariablen des Elternprozesses erben.
deny_env	list[str]	Blockierte Umgebungsvariablen.
snapshot	bool	Dateisystemänderungen aufzeichnen.
restore	bool	Aufzeichnen und nach dem Beenden zurücksetzen. Impliziert snapshot.
snapshot_paths / snapshot_exclude	list[str]	Verfolgte Pfade / ausgeschlossene Muster.
secrets	dict[str, SecretConfig]	Secrets mit host-spezifischen Geltungsbereichen.
debug	bool	Sandbox-Konfiguration auf stderr ausgeben.

Unbekannte Dict-Schlüssel (z. B. versehentlich allowWrite statt allow_write) lösen zur Konstruktionszeit einen TypeError aus.

Einschränkungen

Sandbox.py(code) führt dasjenige python3 aus, das sich im PATH innerhalb der Sandbox befindet. Wenn Ihr aktiver Interpreter außerhalb der lesbaren Wurzelverzeichnisse der Sandbox liegt (zum Beispiel uv-verwaltete Pythons unter ~/.local/share/uv/), greifen Sie stattdessen auf Folgendes zurück:

import sys
sandbox = Sandbox.create({"allow_read": [sys.prefix]})
sandbox.exec(sys.executable, ["-c", "print('hi')"]).text()

Weitere SDKs

• TypeScript SDK (npm: zerobox)
• Rust SDK (crates.io: zerobox)

Lizenz

Apache-2.0