sandcastle
ライブラリmattpocock/sandcastle
TypeScriptライブラリ、サンドボックス化されたAIコーディングエージェントをオーケストレーションするための。
概要
Sandcastleは、隔離されたサンドボックスでAIコーディングエージェントを実行するTypeScriptライブラリで、Docker、Podman、Vercelをネイティブサポートします。サンドボックス、ブランチ、マージコミットを扱うプログラミングAPIを提供し、並列エージェント実行やレビューパイプラインをサポートします。
README プレビュー
\n \n \n \n \n \n\n\n## What Is Sandcastle?\n\nA TypeScript library for orchestrating AI coding agents in isolated sandboxes:\n\n1. You invoke agents with a single `sandcastle.run()`.\n2. Sandcastle handles sandboxing the agent with a configurable branch strategy.\n3. The commits made on the branches get merged back.\n\nSandcastle is provider-agnostic — it ships with built-in providers for Docker, Podman, and Vercel, and you can create your own. Great for parallelizing multiple AFK agents, creating review pipelines, or even just orchestrating your own agents.\n\n## Prerequisites\n\n- [Git](https://git-scm.com/)\n- A sandbox provider — Sandcastle needs an isolated environment to run agents in. Built-in options:\n - [Docker Desktop](https://www.docker.com/) — most common for local development\n - [Podman](https://podman.io/) — rootless alternative to Docker\n - [Vercel](https://vercel.com/) — cloud-based Firecracker microVMs via `@vercel/sandbox`\n - Or [create your own](#custom-sandbox-providers) using `createBindMountSandboxProvider` or `createIsolatedSandboxProvider`\n\n## Quick start\n\n1. Install the package:\n\n```bash\nnpm install --save-dev @ai-hero/sandcastle\n```\n\n2. Run `sandcastle init`. This scaffolds a `.sandcastle` directory with all the files needed.\n\n```bash\nnpx sandcastle init\n```\n\n3. Edit `.sandcastle/.env` and fill in your default values for `ANTHROPIC_API_KEY`. If you want to use your Claude subscription instead of an API key, see [#191](https://github.com/mattpocock/sandcastle/issues/191).\n\n```bash\ncp .sandcastle/.env.example .sandcastle/.env\n```\n\n4. Run the `.sandcastle/main.ts` (or `main.mts`) file with `npx tsx`\n\n```bash\nnpx tsx .sandcastle/main.ts\n```\n\n```typescript\n// 3. Run the agent via the JS API\nimport { run, claudeCode } from "@ai-hero/sandcastle";\nimport { docker } from "@ai-hero/sandcastle/sandboxes/docker";\n\nawait run({\n agent: claudeCode("claude-opus-4-7"),\n sandbox: docker(), // or podmanFAQ (3)
how_tosandcastleで複数のpromptsにわたってagentの会話を続ける方法は？
run()が返すRunResultオブジェクトのresume(prompt)メソッドを使用します。例: const r = await run({ agent: claudeCode('claude-opus-4-6'), sandbox: docker(), prompt: 'draft a plan' }); await r.resume('now execute the plan');。これにより、完全なコンテキストを保持したままエージェントセッションを継続でき、手動でsessionIdを渡す必要がなくなり、サンドボックスの再構築も回避できます。@ai-hero/sandcastleで利用可能です。
トラブル対応createSandboxが同じブランチで複数回実行された場合、なぜ古いブランチを保持するのですか？
サンドボックスは最初の実行時のブランチのローカルクローンを再利用するため、以降の実行では最新の変更をプルしません。回避策: onSandboxReady フックを追加して、ワークスペース内で git pull origin <branch> を実行します。
トラブル対応"PromptExpansionTimeoutError" が発生してシェル展開がタイムアウトした際に、@ai-hero/sandcastle で実行全体がクラッシュする問題を修正する方法は？
プロンプト内のシェルコマンドにリトライラッパーを適用します。例えば、!\\gh api graphql ...\\` を !\\for i in 1 2 3; do gh api graphql ... && break; sleep 2; done\\` に置き換えます。これにより、トークンキャッシュの競合やAPIの停滞のような一時的な不具合を処理できます。アップストリームライブラリがネイティブリトライを追加するまで（issue #617を追跡）、この手動ループによって単一のタイムアウトがAFK実行を中断するのを防ぎます。競合が続く場合は、並列サンドボックスエージェントを減らしてください。