shuru

Shuru によるサンドボックス実行

Shuru は macOS 上で一時的な Linux マイクロ VM（Debian、ARM64）を起動します。Linux ARM64 ホストでも実験的にサポートされています。各 shuru run は新しいディスククローンを使用し、終了時にすべての変更が破棄されます。ホストから隔離してコマンドを実行する必要があるときに使用してください。

基本的なワークフロー

基本の流れは、サンドボックス内で実行し、ファイルの共有にはマウントを使い、状態を保持するにはチェックポイントを作成し、すぐに使える環境にはレシピを使うことです。

# 1. Run a command in a fresh VM
shuru run -- echo "hello from the sandbox"

# 2. Mount the project directory so the VM can access host files
shuru run --mount ./src:/workspace -- ls /workspace

# 3. If the command needs network access (install packages, fetch data)
shuru run --allow-net -- sh -c 'apt-get install -y curl && curl https://example.com'

# 4. If setup is expensive, save a checkpoint and reuse it
shuru checkpoint create node-env --allow-net -- apt-get install -y nodejs npm
shuru run --from node-env --mount .:/workspace -- node /workspace/app.js

# 5. For Docker or a browser, use a recipe from the official catalog
shuru run --recipe docker -- docker run --rm hello-world
shuru run --recipe browser -p 9222:9222 -- sleep infinity

コマンドの連結

複数の手順が必要な場合は、sh -c を使ってコマンドを連結します。

shuru run --allow-net -- sh -c 'apt-get install -y python3 python3-pip && python3 -c "print(1+1)"'

shuru run --mount .:/workspace -- sh -c 'cd /workspace && ls -la && cat README.md'

基本的なコマンド

実行

shuru run [flags] [-- command...]

# Interactive shell (default when no command given)
shuru run

# Run a single command
shuru run -- whoami

# With resources
shuru run --cpus 4 --memory 4096 --disk-size 8192 -- make -j4

# With networking + port forwarding
shuru run --allow-net -p 8080:80 -- nginx -g 'daemon off;'

# Multiple mounts
shuru run --mount ./src:/src --mount ./data:/data -- ls /src /data

# From a checkpoint
shuru run --from myenv -- npm test

# From a recipe: builds the checkpoint on first use, reuses it after
shuru run --recipe docker -- docker ps

チェックポイント

# Create: boots VM, runs command, saves disk on exit
shuru checkpoint create <name> [flags] [-- command...]

# Stack: create from an existing checkpoint
shuru checkpoint create with-deps --from base-env --allow-net -- npm install

# Update: rebuild in place; the old checkpoint stays until the new build succeeds
shuru checkpoint update base-env --allow-net -- apt-get install -y build-essential git

# Layer onto the existing checkpoint instead of starting over
shuru checkpoint update base-env --from base-env --allow-net -- apt-get install -y jq

# Build a checkpoint from a recipe
shuru checkpoint create docker --recipe docker

# List all checkpoints (shows actual disk usage and recipe source)
shuru checkpoint list

# Delete
shuru checkpoint delete <name>

create は既存の名前を拒否します。チェックポイントを置き換えるには update を使います。ステージング用の名前でビルドし、コマンドが 0 で終了した場合にのみ置き換えるため、更新に失敗しても古いチェックポイントはそのまま残ります。

レシピ

レシピは、バージョン管理されたチェックポイントの説明です。recipe.json とシェルの手順で構成され、GitHub から特定のコミットを指定して取得するか、ローカルディレクトリから読み込みます。公式カタログは superhq-ai/recipes で、現在 docker と browser が提供されています。

shuru recipe list                                   # the official catalog
shuru recipe show docker                            # metadata, services and every step, without booting
shuru run --recipe docker -- docker ps              # build on first use, reuse after
shuru checkpoint create docker --recipe docker      # build explicitly under that name
shuru run --recipe docker --checkpoint ci -- ...    # pick the checkpoint name
shuru checkpoint update docker --recipe docker      # force a rebuild at the current revision
shuru run --recipe owner/repo/path@v1 --yes -- ...  # third-party, pinned to a tag
shuru run --recipe ./my-recipe -- ...               # local directory while developing one

スクリプト作成時に重要なルールは次のとおりです。

• docker のような名前だけを指定した場合、常に公式カタログを意味します。ローカルディレクトリはパス（./dir、../dir、/abs、~/dir）で指定する必要があります。
• 公式レシピとローカルレシピは、確認を求めずにビルドされます。サードパーティ製の GitHub レシピでは確認が求められるため、非対話型の実行では --yes を渡してください。
• 参照先はコミット SHA に解決され、チェックポイントとともに記録されます。レシピが変更されている場合、次回の run --recipe で再ビルドされます。変更がなければ、既存のチェックポイントが数秒で起動します。
• ビルドでは、プロジェクトの shuru.json ではなく、レシピで宣言されたネットワーク許可リストが使用されます。docker または browser の初回ビルドには数分かかります。

recipe.json の形式とゲストサービスについては、references/recipes.md を参照してください。

その他のコマンド

# Download/update OS image
shuru init
shuru init --force    # re-download even if up to date

# Upgrade CLI + OS image
shuru upgrade

# Clean up leftover data from crashed VMs
shuru prune

よくあるパターン

開発環境のセットアップ

依存関係をすべて事前にインストールしたチェックポイントを作成し、高速な実行に利用します。

# One-time setup
shuru checkpoint create python-dev --allow-net -- sh -c 'apt-get install -y python3 python3-pip && pip install pytest requests'

# Fast subsequent runs
shuru run --from python-dev --mount .:/workspace -- sh -c 'cd /workspace && pytest'

VM 内の Docker

docker レシピは Docker Engine をインストールし、ゲストサービスとして dockerd を実行し、nginxinc/nginx-unprivileged:1.31.7-alpine-slim を事前にプルします。docker info が応答してからコマンドが開始されます。

# Build once (a few minutes), then every run boots in seconds
shuru checkpoint create docker --recipe docker

# Serve the pre-pulled image on host port 8080; no --allow-net needed
shuru run --from docker -p 8080:8080 -- \
  docker run --rm -p 8080:8080 nginxinc/nginx-unprivileged:1.31.7-alpine-slim

# Pulling other images needs network
shuru run --from docker --allow-net -- docker run --rm python:3.12-alpine python3 -c 'print(1)'

# Build an image from a mounted project
shuru run --from docker --mount .:/app -- sh -c 'cd /app && docker build -t app . && docker run --rm app'

コンテナにもゲストプロセスと同じ境界が適用されます。--allow-net を指定しない限り外部への通信はできず、ホストの許可リストが適用され、ホストポートは -p を通じてのみ開かれます。VM 内では Docker のデフォルト設定を維持してください。--privileged を使ったり、Docker ソケットをマウントしたりしないでください。

ヘッドレスブラウザー（CDP）

browser レシピは、VM 内のポート 9222 で DevTools プロトコルを使用し、権限のないユーザーとして Chromium をヘッドレスで実行します。このポートを転送し、任意の CDP クライアント（Playwright、Puppeteer、browser-use）から http://127.0.0.1:9222 を指定してください。

# Keep the VM alive while a client on the host drives the browser
shuru run --recipe browser -p 9222:9222 -- sleep infinity

# In another terminal
curl -s http://127.0.0.1:9222/json/version

Chromium はマイクロ VM 内で動作し、ホストに届くのは CDP ポートだけです。実際の Web サイトをブラウザーで読み込む必要がある場合は --allow-net を追加し、接続先を制限するには --allow-host を追加してください。DevTools の HTTP エンドポイントは HTTP/1.0 リクエストを無視するため、通常の HTTP/1.1 クライアントを使用してください。

信頼できないコードのテスト

ネットワークへのアクセスとホストのファイルシステムへのアクセスを許可せずに、信頼できないスクリプトを実行します。

# Fully isolated: no --allow-net, no --mount
shuru run -- sh -c 'echo "malicious script here" && rm -rf / 2>/dev/null; echo "host is safe"'

ビルドとテスト

ソースをマウントして VM 内でビルドすると、マウント経由でホストに結果が表示されます。

shuru run --mount .:/workspace --cpus 4 --memory 4096 -- sh -c '
  cd /workspace
  apt-get install -y build-essential
  make -j4
  make test
'

Web サーバーのポート転送

shuru run --allow-net --from node-env -p 3000:3000 --mount .:/app -- sh -c '
  cd /app && node server.js
'
# Access at http://localhost:3000 on the host

チェックポイントの積み重ね

環境を段階的にビルドします。

shuru checkpoint create base --allow-net -- apt-get install -y build-essential git curl
shuru checkpoint create node --from base --allow-net -- apt-get install -y nodejs npm
shuru checkpoint create project --from node --allow-net --mount .:/app -- sh -c 'cd /app && npm install'
# Now "project" has OS deps + Node + node_modules baked in
shuru run --from project --mount .:/app -- sh -c 'cd /app && npm test'

プロジェクト設定（shuru.json）

フラグを繰り返し指定しなくて済むように、プロジェクトのルートに shuru.json を配置します。

{
  "cpus": 2,
  "memory": 2048,
  "disk_size": 4096,
  "allow_net": true,
  "ports": ["8080:80"],
  "mounts": ["./src:/workspace"],
  "command": ["/bin/sh", "-c", "cd /workspace && sh"],
  "secrets": {
    "API_KEY": {
      "from": "OPENAI_API_KEY",
      "hosts": ["api.openai.com"]
    }
  },
  "network": {
    "allow": ["api.openai.com", "registry.npmjs.org"]
  }
}

CLI フラグは設定値より優先されます。secrets を設定すると、ゲストにはプレースホルダートークンが渡され、許可されたホストへの HTTPS リクエストではプロキシが実際の値に置き換えます。command でシークレットを発行し、有効期限が切れる前に更新することもできます。すべてのフィールドについては、references/config.md を参照してください。

重要な制約

• ネットワークはデフォルトで無効です。 パッケージのインストールや HTTP リクエストを行うには、--allow-net を指定する必要があります。-p によるポートフォワーディングは、指定しなくても利用できます。
• ゲストは Debian Linux（aarch64）です。 パッケージのインストールには apt-get install を使用してください。
• デフォルトでは一時的です。 チェックポイントを作成しない限り、終了時にすべて破棄されます。
• マウントはデフォルトで読み取り専用です。 ゲストからの書き込みは tmpfs オーバーレイに保存され、終了時に破棄されます。ホストに書き込むには、:rw サフィックスと --allow-host-writes を使用してください。
• ゲストに systemd はありません。 長時間実行するデーモンはゲストサービスとして宣言します（references/recipes.md を参照）。systemctl は存在しません。
• Apple Silicon 搭載の macOS に加え、/dev/kvm がある実験的な Linux ARM64 ホストに対応しています。
• デフォルトのリソース： CPU 2 個、RAM 2048 MB、ディスク 4096 MB です。--cpus、--memory、--disk-size で変更できます。

詳細ドキュメント

• references/checkpoints.md：チェックポイントのライフサイクル、更新、スタック、ディスク使用量
• references/recipes.md：recipe.json の形式、参照、信頼、ゲストサービス
• references/config.md：shuru.json のフィールドと解決順序
• references/networking.md：allow-net、ポートフォワーディング、プロキシの動作