Zerobox Python SDK

Python SDK は zerobox のためのSDKです。ファイル、ネットワーク、認証情報の制御で任意のコマンドをサンドボックス化します。

pip install zerobox

wheel をインストールすると、zerobox CLI が環境の bin/ に配置され、Python SDK が利用可能になります。

CLI の使い方、シークレットの概念、フルフラグリファレンス、パフォーマンス数値、プラットフォームサポートについては、メイン README を参照してください。

クイックスタート

from zerobox import Sandbox

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

コマンド

コマンドを実行する3つの方法。それぞれが ShellCommand を返し、.text()、.json()、または .output() で終了します。

シェル

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

インライン Python

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

明示的なコマンド + 引数

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

結果

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

非同期 API

非同期アプリケーションでは AsyncSandbox を使用して、サンドボックス化されたサブプロセスの待機がイベントループをブロックしないようにします。コマンドの形は Sandbox と同じですが、作成と終了は 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()

非同期コマンドも同じ timeout オプションを受け付けます：

import subprocess

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

エラーハンドリング

非ゼロ終了は SandboxCommandError を発生させます：

from zerobox import Sandbox, SandboxCommandError

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

シークレット

サンドボックス化されたプロセスが決して見ることのない API キーを渡します。プロキシは承認されたホストに対してのみ実際の値を置き換えます。

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

プレースホルダーの置換の仕組みについては、メイン README を参照してください。

スナップショット

ファイルシステムの変更を記録し、自動的にロールバックします：

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

ロールバックせずに記録する：

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

キャンセル

任意の終了メソッドに timeout (秒) を渡します：

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

環境変数

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

デフォルトで継承されるものと CLI での同等の設定については、メイン README を参照してください。

オプション

Sandbox.create(options) は SandboxOptions データクラスまたはプレーンな dict を受け付けます。すべてのフィールドはオプションです。

未知の dict キー（例：allow_write の代わりに誤った allowWrite）は、構築時に TypeError を発生させます。

注意点

Sandbox.py(code) は、サンドボックス内の PATH にある python3 を実行します。アクティブなインタープリタがサンドボックスの読み取り可能ルートの外にある場合（例：~/.local/share/uv/ 以下の uv 管理の Python）、フォールバックとして以下を使用します：

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

他の SDK

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

ライセンス

Apache-2.0

`.text()`	標準出力を文字列として返す	`SandboxCommandError` を発生させる
`.json()`	標準出力をJSONとしてパースする	`SandboxCommandError` を発生させる
`.output()`	`CommandOutput(code, stdout, stderr)` を返す	同じ形を返し、決して例外を発生させない

`profile`	`str \| list[str]`	名前付きプロファイル。リストの場合は左から右にマージされます。デフォルトは `"workspace"`。
`allow_read` / `deny_read`	`list[str]`	読み取り可能/ブロックされたパス。
`allow_write` / `deny_write`	`list[str]`	書き込み可能/ブロックされたパス。
`allow_net`	`bool \| list[str]`	`True` はすべてを許可します。リストの場合はそのドメインに制限されます。
`deny_net`	`list[str]`	ブロックされたドメイン。
`allow_all`	`bool`	完全なファイルシステム + ネットワークアクセス。
`no_sandbox`	`bool`	サンドボックスを完全に無効にする。
`strict_sandbox`	`bool`	弱い分離にフォールバックする代わりに失敗する。
`cwd`	`str`	作業ディレクトリ。
`env`	`dict[str, str]`	明示的な環境変数。
`allow_env`	`bool \| list[str]`	親の環境変数を継承する。
`deny_env`	`list[str]`	ブロックされた環境変数。
`snapshot`	`bool`	ファイルシステムの変更を記録する。
`restore`	`bool`	終了後に記録してロールバックする。`snapshot` を含意。
`snapshot_paths` / `snapshot_exclude`	`list[str]`	追跡するパス / 除外パターン。
`secrets`	`dict[str, SecretConfig]`	ホストごとのスコープを持つシークレット。
`debug`	`bool`	サンドボックス設定を stderr に出力する。

zerobox

人気