SDK Python di Zerobox

SDK Python per zerobox. Esegui in sandbox qualsiasi comando con controlli su file, rete e credenziali.

pip install zerobox

L'installazione del wheel inserisce la CLI zerobox nella directory bin/ del tuo ambiente ed espone un SDK Python.

Per l'uso da CLI, i concetti dei segreti, il riferimento completo alle flag, i numeri di performance e il supporto alle piattaforme, consulta il README principale.

Avvio rapido

from zerobox import Sandbox

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

Comandi

Tre modi per eseguire un comando. Ognuno restituisce un ShellCommand che termina con .text(), .json() o .output().

Shell

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

Python inline

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

Comando esplicito + argomenti

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

Risultati

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

API asincrona

Usa AsyncSandbox in applicazioni asincrone in modo che l'attesa del sottoprocesso in sandbox non blocchi il loop degli eventi. La forma dei comandi è la stessa di Sandbox, ma la creazione e i terminatori sono in attesa (await).

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()

I comandi asincroni accettano la stessa opzione timeout:

import subprocess

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

Gestione degli errori

Un'uscita non-zero solleva SandboxCommandError:

from zerobox import Sandbox, SandboxCommandError

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

Segreti

Passa chiavi API che il processo in sandbox non vede mai. Il proxy sostituisce il valore reale solo per host approvati.

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()

Vedi il README principale per come funziona la sostituzione dei placeholder.

Snapshots

Registra le modifiche al filesystem e annullale automaticamente:

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

Registra senza annullare:

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

Cancellazione

Passa un timeout (secondi) a qualsiasi terminatore:

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

Variabili d'ambiente

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

Vedi il README principale per cosa viene ereditato di default e gli equivalenti CLI.

Opzioni

Sandbox.create(options) accetta un dataclass SandboxOptions o un dict semplice. Tutti i campi sono opzionali.

Chiavi di dict sconosciute (ad esempio allowWrite invece di allow_write) sollevano TypeError al momento della costruzione.

Avvertenze

Sandbox.py(code) esegue il python3 presente nel PATH all'interno della sandbox. Se il tuo interprete attivo si trova al di fuori delle radici leggibili della sandbox (ad esempio Python gestiti da uv in ~/.local/share/uv/), usa invece:

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

Altri SDK

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

Licenza

Apache-2.0

`.text()`	Restituisce stdout come stringa	Solleva `SandboxCommandError`
`.json()`	Analizza stdout come JSON	Solleva `SandboxCommandError`
`.output()`	Restituisce `CommandOutput(code, stdout, stderr)`	Restituisce la stessa forma, non solleva mai

`profile`	`str \| list[str]`	Profili nominati. Una lista li unisce da sinistra a destra. Default `"workspace"`.
`allow_read` / `deny_read`	`list[str]`	Percorsi leggibili / bloccati.
`allow_write` / `deny_write`	`list[str]`	Percorsi scrivibili / bloccati.
`allow_net`	`bool \| list[str]`	`True` permette tutto. Una lista li limita a quei domini.
`deny_net`	`list[str]`	Domini bloccati.
`allow_all`	`bool`	Accesso completo a filesystem e rete.
`no_sandbox`	`bool`	Disabilita completamente la sandbox.
`strict_sandbox`	`bool`	Fallisce invece di ripiegare su un isolamento più debole.
`cwd`	`str`	Directory di lavoro.
`env`	`dict[str, str]`	Variabili d'ambiente esplicite.
`allow_env`	`bool \| list[str]`	Eredita le variabili d'ambiente del genitore.
`deny_env`	`list[str]`	Variabili d'ambiente bloccate.
`snapshot`	`bool`	Registra le modifiche al filesystem.
`restore`	`bool`	Registra e annulla dopo l'uscita. Implica `snapshot`.
`snapshot_paths` / `snapshot_exclude`	`list[str]`	Percorsi tracciati / pattern esclusi.
`secrets`	`dict[str, SecretConfig]`	Segreti con ambiti per host.
`debug`	`bool`	Stampa la configurazione della sandbox su stderr.

zerobox

Più Popolari