Claude CodeやCodexを複数同時に走らせたい。でもローカル環境で直接実行すると、ファイルの競合やブランチの衝突が起きる。Sandcastleは、この問題をサンドボックス隔離で解決するオープンソースのオーケストレーターです。

この記事でわかること

  • Sandcastleが解決するAIエージェント並列実行の課題
  • Docker、Podman、Vercelに対応したサンドボックスの仕組み
  • sandcastle.run() 1行で始める導入手順
  • マージフローとレビューパイプラインの使い方
  • 類似ツールとの違い

AIエージェントをローカルで直接動かすリスク

https://github.com/mattpocock/sandcastle

AIコーディングエージェントは、ファイルの作成、編集、削除を自律的に行います。1つのエージェントだけなら問題になりにくいですが、複数を同時に走らせると状況が変わります。

同じファイルを2つのエージェントが同時に編集すれば競合が起きます。片方が依存パッケージを更新している最中に、もう片方がビルドを実行すれば失敗します。最悪の場合、作業中のコードが上書きされて成果物が消えます。

SandcastleはTypeScript製のオーケストレーションライブラリで、エージェントごとに隔離されたサンドボックスを自動で立ち上げます。各サンドボックスは独立したファイルシステムとGitブランチを持つため、エージェント同士が干渉しません。作業が終わると、コミットがホスト側のリポジトリに自動でマージされます。

開発者はMatt Pocock氏。TypeScript教育で知られるエンジニアで、GitHubスター数は約3,000、ライセンスはMITです。

3つのサンドボックスプロバイダー

Sandcastleはプロバイダーを差し替えられる設計です。実行環境に応じて3つの選択肢があります。

Dockerはローカル開発で最も一般的な選択です。Docker Desktopがインストールされていれば、追加設定なしで使えます。エージェントの実行がコンテナ内に閉じるため、ホスト環境に影響を与えません。

PodmanはDockerのルートレス代替です。デーモン不要で動くため、セキュリティポリシーが厳しい環境に向いています。

VercelはクラウドベースのFirecracker microVMを使います。@vercel/sandboxパッケージ経由で接続し、ローカルにDockerを入れたくない場合や、CIパイプラインから実行したい場合に適しています。

この3つ以外にも、createBindMountSandboxProviderやcreateIsolatedSandboxProviderを使って独自プロバイダーを作れます。

導入手順

必要なものはNode.jsとGit、そしていずれかのサンドボックスプロバイダーです。

まずパッケージをインストールします。

npm install --save-dev @ai-hero/sandcastle

次に初期設定ファイルを生成します。

npx sandcastle init

このコマンドで.sandcastleディレクトリが作られ、設定ファイルとプロンプトテンプレートが配置されます。.sandcastle/.envにAPIキーを設定すれば準備完了です。

実行は.sandcastle/main.tsをそのまま走らせるか、TypeScriptコードからrun()を呼び出します。

import { run, claudeCode } from "@ai-hero/sandcastle";
import { docker } from "@ai-hero/sandcastle/sandboxes/docker";

await run({
  agent: claudeCode("claude-opus-4-6"),
  sandbox: docker(),
  promptFile: ".sandcastle/prompt.md",
});

agentにはClaude Codeが組み込みで用意されています。sandboxでプロバイダーを指定し、promptFileでエージェントへの指示を渡します。これだけでサンドボックスの起動からブランチ作成、エージェント実行、コミットのマージまでが自動で行われます。

マージフローで並列作業を統合する

Sandcastleの強みは、複数エージェントの成果物を安全に統合する仕組みにあります。

sandcastle initで生成されるテンプレートには、用途別のマージフローが含まれています。simple-loopは1つのエージェントを繰り返し実行する基本形です。sequential-reviewerはエージェントの出力を別のエージェントがレビューする直列パイプラインです。parallel-plannerは計画フェーズで分割されたタスクを複数エージェントが並列で処理します。

並列実行では、各エージェントが独立したブランチで作業します。全員が終了すると、Sandcastleがブランチをメインに順次マージします。コンフリクトが発生した場合は、設定に応じて自動解決を試みるか、ユーザーに通知します。

類似ツールとの違い

AIエージェントの並列実行を支援するツールは他にもあります。Orcaは複数エージェントを一画面で操作するデスクトップIDEで、git worktreeベースの分離を提供します。Kandevはサーバーサイドの看板ボードでタスクを管理します。

Sandcastleが異なるのは、ライブラリとして提供される点です。GUIやWebダッシュボードではなく、TypeScriptのコードから直接制御します。CIパイプラインへの組み込みや、独自のワークフロー構築がしやすい設計です。サンドボックスプロバイダーの差し替えが可能な点も、インフラ要件が異なるチーム間での採用を容易にしています。

まとめ

AIコーディングエージェントの並列実行は、単にプロセスを複数起動するだけでは安全に機能しません。ファイル競合、ブランチ衝突、環境汚染というリスクがあります。Sandcastleはサンドボックスによる隔離とGitブランチ戦略の自動化で、これらの問題をライブラリレベルで解決します。TypeScriptプロジェクトでAIエージェントを本格活用するなら、検討する価値があります。