Zerobox Python SDK

SDK Python para zerobox. Execute qualquer comando em sandbox com controles de arquivo, rede e credenciais.

pip install zerobox

A instalação da wheel coloca a CLI zerobox no bin/ do seu ambiente e expõe um SDK Python.

Para uso da CLI, conceitos de segredos, a referência completa de flags, números de desempenho e suporte de plataforma, consulte o README principal.

Início rápido

from zerobox import Sandbox

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

Comandos

Três maneiras de executar um comando. Cada uma retorna um ShellCommand que você finaliza com .text(), .json() ou .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 explícito + argumentos

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

Resultados

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

API assíncrona

Use AsyncSandbox em aplicações assíncronas para que a espera pelo subprocesso em sandbox não bloqueie o event loop. A estrutura do comando é a mesma do Sandbox, mas a criação e os terminadores são aguardados com 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()

Comandos assíncronos aceitam a mesma opção timeout:

import subprocess

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

Tratamento de erros

Código de saída diferente de zero lança SandboxCommandError:

from zerobox import Sandbox, SandboxCommandError

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

Segredos

Passe chaves de API que o processo em sandbox nunca vê. O proxy substitui o valor real apenas para hosts aprovados.

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

Consulte o README principal para saber como funciona a substituição de placeholders.

Snapshots

Registre alterações no sistema de arquivos e reverta-as automaticamente:

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

Registre sem reverter:

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

Cancelamento

Passe um timeout (em segundos) para qualquer terminador:

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

Variáveis de ambiente

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

Consulte o README principal para saber o que é herdado por padrão e os equivalentes da CLI.

Opções

Sandbox.create(options) aceita um dataclass SandboxOptions ou um dict simples. Todos os campos são opcionais.

Chaves de dict desconhecidas (por exemplo, allowWrite acidental em vez de allow_write) lançam TypeError na construção.

Ressalvas

Sandbox.py(code) executa o python3 que estiver no PATH dentro do sandbox. Se o seu interpretador ativo estiver fora das raízes legíveis do sandbox (por exemplo, Pythons gerenciados por uv em ~/.local/share/uv/), recorra a:

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

Outros SDKs

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

Licença

Apache-2.0

`.text()`	Retorna stdout como string	Lança `SandboxCommandError`
`.json()`	Analisa stdout como JSON	Lança `SandboxCommandError`
`.output()`	Retorna `CommandOutput(code, stdout, stderr)`	Retorna a mesma estrutura, nunca lança exceção

`profile`	`str \| list[str]`	Perfil(is) nomeado(s). Uma lista é mesclada da esquerda para a direita. Padrão `"workspace"`.
`allow_read` / `deny_read`	`list[str]`	Caminhos legíveis / bloqueados.
`allow_write` / `deny_write`	`list[str]`	Caminhos graváveis / bloqueados.
`allow_net`	`bool \| list[str]`	`True` permite tudo. Uma lista restringe a esses domínios.
`deny_net`	`list[str]`	Domínios bloqueados.
`allow_all`	`bool`	Acesso total ao sistema de arquivos + rede.
`no_sandbox`	`bool`	Desativa o sandbox completamente.
`strict_sandbox`	`bool`	Falha em vez de recorrer a um isolamento mais fraco.
`cwd`	`str`	Diretório de trabalho.
`env`	`dict[str, str]`	Variáveis de ambiente explícitas.
`allow_env`	`bool \| list[str]`	Herdar variáveis de ambiente do processo pai.
`deny_env`	`list[str]`	Variáveis de ambiente bloqueadas.
`snapshot`	`bool`	Registra alterações no sistema de arquivos.
`restore`	`bool`	Registra e reverte após a saída. Implica `snapshot`.
`snapshot_paths` / `snapshot_exclude`	`list[str]`	Caminhos monitorados / padrões excluídos.
`secrets`	`dict[str, SecretConfig]`	Segredos com escopos por host.
`debug`	`bool`	Imprime a configuração do sandbox em stderr.

zerobox

Mais Populares