**Show HN：** 「Zerobox – ファイル・ネットワーク・認証情報を制御して任意のコマンドをサンドボックス化」

ファイル・ネットワーク・認証情報を制御したサンドボックス化

OpenAI Codex のサンドボックスランタイムで実現する、軽量かつクロスプラットフォームのプロセスサンドボックス。

• デフォルトで拒否：書き込み、ネットワーク、環境変数は明示的に許可しない限りブロック。
• 認証情報注入：プロセスが直接見られないよう API キーを渡す；Zerobox は承認されたホストのみに実際の値を注入。
• ファイルアクセス制御：特定パスへの読み書きを許可または拒否。
• ネットワークフィルタリング：ドメイン単位でアウトバウンド通信を許可/拒否。
• クリーン環境：PATH、HOME など必須の env のみデフォルト継承。
• TypeScript SDK：

  import { Sandbox } from "zerobox"

  （Deno風 API）。
• クロスプラットフォーム：macOS と Linux に対応；Windows は計画中。
• 単一バイナリ：Docker や VM 不要、オーバーヘッドは約 10 ms。

インストール

Shell (macOS / Linux)

curl -fsSL https://raw.githubusercontent.com/afshinm/zerobox/main/install.sh | sh

npm

npm install zerobox

ソースからビルド

git clone https://github.com/afshinm/zerobox && cd zerobox
./scripts/sync.sh && cargo build --release -p zerobox

速攻開始

• 書き込みとネットワークを許可しないコマンド実行：

zerobox -- node -e "console.log('hello')"

• 特定ディレクトリへの書き込み許可：

zerobox --allow-write=. -- node script.js

• 特定ドメインへのネットワーク許可：

zerobox --allow-net=api.openai.com -- node agent.js

• 特定ホストにのみシークレットを渡す（内部プロセスは実際の値を見ない）：

zerobox \
  --secret OPENAI_API_KEY=sk-proj-123 \
  --secret-host OPENAI_API_KEY=api.openai.com \
  -- node agent.js

TypeScript SDK

import { Sandbox } from "zerobox";

const sandbox = Sandbox.create({
  secrets: {
    OPENAI_API_KEY: {
      value: process.env.OPENAI_API_KEY,
      hosts: ["api.openai.com"],
    },
  },
});

const output = await sandbox.sh`node agent.js`.text();

アーキテクチャ

Secrets

API キー・トークンなどのシークレットはサンドボックス内では決して表示されない。
プロセスにはプレースホルダーが渡り、ネットワークプロキシレベルで要求されたホストに対してのみ実際の値を差し替える。

例：

# サンドボックス内
echo $OPENAI_API_KEY   # → ZEROBOX_SECRET_a1b2c3d4...
curl -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/...  
# プロキシがプレースホルダーを実際のキーに置き換えて送信

CLI の使用

zerobox \
  --secret OPENAI_API_KEY=sk-proj-123 \
  --secret-host OPENAI_API_KEY=api.openai.com \
  -- node app.js

--secret-host

zerobox --secret TOKEN=abc123 -- node app.js

複数のシークレットとホストを組み合わせられる。

注意：Node.js の

fetch

はデフォルトで

HTTPS_PROXY

を尊重しない。サンドボックス内でシークレットを使う場合は

--use-env-proxy

引数を渡す。

TypeScript SDK

import { Sandbox } from "zerobox";

const sandbox = Sandbox.create({
  secrets: {
    OPENAI_API_KEY: {
      value: process.env.OPENAI_API_KEY,
      hosts: ["api.openai.com"],
    },
    GITHUB_TOKEN: {
      value: process.env.GITHUB_TOKEN,
      hosts: ["api.github.com"],
    },
  },
});

await sandbox.sh`node agent.js`.text();

環境変数

デフォルトでは PATH、HOME、USER、SHELL、TERM、LANG のみ継承。

• 親プロセスのすべてを継承：

  zerobox --allow-env -- node app.js
  

• 指定した env だけ継承：

  zerobox --allow-env=PATH,HOME,DATABASE_URL -- node app.js
  

• 特定の env をブロック：

  zerobox --allow-env --deny-env=AWS_SECRET_ACCESS_KEY -- node app.js
  

• 環境変数を設定：

  zerobox --env NODE_ENV=production --env DEBUG=false -- node app.js
  

TypeScript SDK

const sandbox = Sandbox.create({
  env: { NODE_ENV: "production" },
  allowEnv: ["PATH", "HOME"],
  denyEnv: ["AWS_SECRET_ACCESS_KEY"],
});

例

AI が生成したコードを安全に実行

zerobox -- python3 /tmp/task.py

出力ディレクトリへの書き込みのみ許可：

zerobox --allow-write=/tmp/output -- python3 /tmp/task.py

SDK を使う場合：

import { Sandbox } from "zerobox";

const sandbox = Sandbox.create({
  allowWrite: ["/tmp/output"],
  allowNet: ["api.openai.com"],
});

const result = await sandbox.sh`python3 /tmp/task.py`.output();
console.log(result.code, result.stdout);

LLM ツール呼び出しを制限

各 AI ツール呼び出しは個別にサンドボックス化可能。

import { Sandbox } from "zerobox";

const reader  = Sandbox.create();
const writer  = Sandbox.create({ allowWrite: ["/tmp"] });
const fetcher = Sandbox.create({ allowNet: ["example.com"] });

const data = await reader.js`
  const content = require("fs").readFileSync("/tmp/input.txt", "utf8");
  console.log(JSON.stringify({ content }));
`.json();

await writer.js`
  require("fs").writeFileSync("/tmp/output.txt", "result");
  console.log("ok");
`.text();

const result = await fetcher.js`
  const res = await fetch("https://example.com");
  console.log(JSON.stringify({ status: res.status }));
`.json();

完全動作例：

• examples/ai-agent-sandboxed

  – シークレット付きでエージェントプロセス全体をサンドボックス化（API キーは可視化されない）。

• examples/ai-agent

  – Vercel AI SDK でツールごとにサンドボックス化し、シークレットを使用。

• examples/workflow

  – Vercel Workflow の耐久ステップをサンドボックス化。

ビルド時にリポジトリを保護

# ネットワークアクセスが必要なビルドスクリプト
zerobox --allow-write=./dist --allow-net -- npm run build

# ネットワークなしでテスト（外部呼び出しの誤検知）
zerobox --allow-write=/tmp -- npm test

SDK 参照

シェルコマンド

import { Sandbox } from "zerobox";

const sandbox = Sandbox.create({ allowWrite: ["/tmp"] });
const output = await sandbox.sh`echo hello`.text();

JSON 出力

const data = await sandbox.sh`cat data.json`.json();

生出力（非ゼロ終了時にエラーを投げない）

const result = await sandbox.sh`exit 42`.output();
// { code: 42, stdout: "", stderr: "" }

明示的なコマンド + 引数

await sandbox.exec("node", ["-e", "console.log('hi')"]).text();

インライン JavaScript

const data = await sandbox.js`
  console.log(JSON.stringify({ sum: 1 + 2 }));
`.json();

エラーハンドリング

非ゼロ終了コードは

SandboxCommandError

import { Sandbox, SandboxCommandError } from "zerobox";

const sandbox = Sandbox.create();
try {
  await sandbox.sh`exit 1`.text();
} catch (e) {
  if (e instanceof SandboxCommandError) {
    console.log(e.code);   // 1
    console.log(e.stderr);
  }
}

キャンセル

const controller = new AbortController();
await sandbox.sh`sleep 60`.text({ signal: controller.signal });

パフォーマンス

サンドボックスのオーバーヘッドは最小で、通常約10 msと7 MB程度。

echo hello

node -e '...'

python3 -c '...'

cat 10 MB file

curl https://...

Apple M5 Pro のウォームアップ後、10 回のベスト実行で測定。再現は

./bench/run.sh

プラットフォームサポート

CLI 参照

--allow-read <paths>

--allow-read=/tmp,/data

--deny-read <paths>

--deny-read=/secret

--allow-read

--allow-write [paths]

--allow-write=.

--deny-write <paths>

--deny-write=./.git

--allow-write

--allow-net [domains]

--allow-net=example.com

--deny-net <domains>

--deny-net=evil.com

--allow-net

--env <KEY=VALUE>

--env NODE_ENV=prod

--allow-env [keys]

--allow-env=PATH,HOME

--deny-env <keys>

--deny-env=SECRET

--allow-env

--secret <KEY=VALUE>

--secret API_KEY=sk-123

--secret-host <KEY=HOSTS>

--secret-host API_KEY=api.openai.com

-A, --allow-all

-A

--no-sandbox

--no-sandbox

--strict-sandbox

--strict-sandbox

--debug

--debug

-C <dir>

-C /workspace

-V, --version

--version

-h, --help

--help

ライセンス

Apache‑2.0