# 在沙盒之外執行你的 harness（原因與方法）
> 📖 本站完整內容索引（documentation index）：[llms.txt](/llms.txt)
> 原作者：Nathan Flurry 🔩 (@NathanFlurry) · 策展與摘要：EasyVibeCoding · 平台：X (Twitter) · 熱度：🔥🔥 · 日期：2026-07-30
> 原始來源：https://x.com/nathanflurry/status/2081768022025658672
## 證據與延伸閱讀
- [自2026年初以來業界正朝沙盒外部執行Agent](https://x.com/nathanflurry/status/2081768022025658672)
## 中文摘要
# 在沙盒之外執行你的 harness（原因與方法）
自 2026 年初以來，關於該在哪裡執行 Agent 一直有一場持續的辯論：應該在沙盒內部，還是在沙盒外部？業界已經有了這兩種做法的實作，但對成熟專案而言，業界正朝著把 Agent 跑在沙盒外的方向走。
在過去幾個月裡，OpenAI、Anthropic、Vercel、Cloudflare 和 Amp 都推出了在沙盒外部執行 Agent 迴圈的平臺。
#
# 在沙盒內部執行 Agent：設定簡單，維護困難
展開畫面重點
畫面最上方有文字「Sandbox」。下方為三個被虛線外框包覆的區塊，每個區塊內部結構完全相同，左側為帶有藍色斜線填滿外框、標示為「Agent」的方塊，透過一條向右的箭頭指向右側標示為「Shell + Files」的紅色斜線填滿方塊。
展開畫面重點
這是一張黑色背景的時序圖（Sequence Diagram），展示了 User、Your API 與 Sandbox 三個實體之間的互動流程。圖中包含的文字與步驟如下：
1. User 向 Your API 發送訊息：「Create agent」。
2. Your API 向 Sandbox 發送訊息：「Create sandbox」。
3. User 向 Your API 發送訊息：「Send prompt」。
4. Your API 呼叫 Sandbox 執行：「Exec Claude CLI with prompt」。
5. Sandbox 端進行藍色虛線區塊的處理：「Process prompt & run tools」。
6. Sandbox 回傳「Response」至 Your API（以虛線箭頭表示）。
7. Your API 回傳「Response」至 User（以虛線箭頭表示）。
展開畫面重點
黑色背景畫面上方顯示手寫風格的文字「Sandbox」，下方有一虛線邊框的圓角矩形區域，框內中央置放著一顆黑色球體炸彈，帶有一條連接至亮黃色燃燒引信的導火線。
展開畫面重點
畫面為純黑色背景，上方正中央以白色手寫風格字體顯示「Sandbox」。下方置有一組由白色虛線構成的圓角方框，框內正中心為一個金屬質感的掛鎖圖示，其金屬環呈開啟狀態。無其他文字或程式碼內容。
展開畫面重點
畫面為全黑背景，上方以手寫風格字體顯示「Sandbox」。下方置中一個由白色虛線組成的圓角方形框，框內包含三個由小到大排列的藍色「Z」字圖示。
展開畫面重點
畫面為一張深色背景的系統架構圖，分為左右兩個主要區塊：左側標示為「Your Backend」，內部包含三個並排的藍色區塊，每個區塊均標示為「Agent」；右側標示為「Sandbox」，內部包含三個對應的紅色區塊，每個區塊均標示為「Shell + Files」。左側的每個 Agent 透過帶箭頭的線條指向右側對應的 Shell + Files。
展開畫面重點
這是一張手繪風格的系統架構圖，背景為黑色，主要分為兩個區域：「Your Backend」與「Sandbox」。
「Your Backend」區塊包含以下元件與關聯：
1. **generateText**：藍色帶有斜線圖示的圓角方框，標有 `generateText`。
2. **LLM Provider**：位於 generateText 下方的圓角方框，標有 `LLM Provider`，generateText 有向下箭頭指向此元件。
3. **Tools**：位於 generateText 右側的圓角方框，標有 `Tools (runCommand, readFile, writeFile)`。generateText 與 Tools 之間有雙向箭頭相連。
「Sandbox」區塊包含：
- **Shell + Files**：紅色帶有斜線圖示的圓角方框，標有 `Shell + Files`。Tools 與此元件之間有向右的箭頭相連，跨越 Backend 與 Sandbox 的虛線邊界。
展開畫面重點
畫面為一段 JavaScript 程式碼，背景為深色。程式碼內容如下：
import { docker } from "@computesdk/docker";
// Boot a sandbox on the local Docker provider. Swap `docker` for any other
// provider (e2b, daytona, vercel, etc.).
const compute = docker({
runtime: "node",
image: { name: "node:22-slim", pullPolicy: "ifNotPresent" },
});
const sandbox = await compute.sandbox.create();
這段程式碼透過 `@computesdk/docker` 匯入 `docker` 模組，並註解說明可在本地 Docker provider 上啟動 sandbox，亦可替換為其他 provider（如 e2b、daytona、vercel 等）。接著建立 `compute` 常數，設定 `runtime` 為 `"node"`，並指定 image 名稱與 `pullPolicy`；最後透過 `await compute.sandbox.create()` 建立 sandbox 實例。
展開畫面重點
畫面為一段以 TypeScript 編寫的程式碼，使用 `import { tool } from "ai";` 與 `import { z } from "zod";` 進行套件引入。
程式碼上方註解說明：
`// The agent's tools run here in your own process. The sandbox only receives`
`// the commands and file operations that the tools send to it.`
定義常數 `const tools = {` 包含了三個工具函式：
1. `runCommand`：
- description: `"Run a shell command in the sandbox"`
- inputSchema: `z.object({ command: z.string().describe("The shell command to run") })`
- execute: 非同步函式，執行 `await sandbox.runCommand(command);` 並回傳 `stdout`、`stderr` 與 `exitCode`。
2. `writeFile`：
- description: `"Write a file in the sandbox"`
- inputSchema: `z.object({ path: z.string().describe("Absolute path of the file"), content: z.string().describe("Full contents of the file") })`
- execute: 非同步函式，執行 `await sandbox.filesystem.writeFile(path, content);` 並回傳 `{ ok: true }`。
3. `readFile`：
- description: `"Read a file from the sandbox"`
- inputSchema: `z.object({ path: z.string().describe("Absolute path of the file") })`
- execute: 非同步函式，回傳 `{ content: await sandbox.filesystem.readFile(path) }`。
展開畫面重點
畫面為一段使用 JavaScript / TypeScript 編寫的程式碼，展示如何透過 `@ai-sdk/anthropic` 與 `ai` 套件建立一個 agent 的互動迴圈。
程式碼逐行轉錄如下：
import * as readline from "node:readline/promises";
import { anthropic } from "@ai-sdk/anthropic";
import { generateText, type ModelMessage, stepCountIs } from "ai";
// Read tasks from the terminal and run the agent on each one
const terminal = readline.createInterface({
input: process.stdin,
output: process.stdout,
});
// The session history
const messages: ModelMessage[] = [];
while (true) {
// Wait for the user to type a task
const prompt = await terminal.question("agent> ");
messages.push({ role: "user", content: prompt });
// Run the agent loop until the task is complete
const result = await generateText({
model: anthropic("claude-sonnet-5"),
system:
"You are a coding agent working inside a fresh Linux sandbox with No...",
"Use the tools to run commands and edit files to complete the user's...",
messages,
tools,
stopWhen: stepCountIs(20),
});
messages.push(...result.response.messages);
console.log(result.text);
}
程式碼重點：
1. **導入套件**：引入 `node:readline/promises` 用於讀取終端機輸入，以及 `@ai-sdk/anthropic` 與 `ai` 的 `generateText`、`ModelMessage`、`stepCountIs`。
2. **初始化介面與對話紀錄**：建立 `terminal` 互動介面，並宣告 `messages` 陣列來維護 `session history`。
3. **主迴圈 (`while (true)`)**：
- 透過 `terminal.question("agent> ")` 等待使用者輸入任務，並將其放入 `messages` 中（角色為 `user`）。
- 呼叫 `generateText` 執行 agent loop，指定模型為 `anthropic("claude-sonnet-5")`。
- 設定 system prompt，宣告其為在 Linux sandbox 中運作的 coding agent，並賦予其使用 tools 執行指令與編輯檔案的權限。
- 帶入 `messages` 與 `tools`，並設定停止條件 `stopWhen: stepCountIs(20)`。
- 將 agent 回應的訊息推回 `messages` 陣列，最後用 `console.log(result.text)` 輸出結果。
展開畫面重點
圖中分為三大直欄：左側為 `Actors`，中間為 `Agent` 相關狀態，右側為 `Sandbox`。上方標題區分別標示 `Actors` 與 `Sandbox`。
圖中包含三個橫列的情境：
1. 第一列：
- 左側 `User A` 連線至中間帶有斜線紋理、標示 `Agent + SQLite` 的藍色方框，外圍有虛線框。
- 中間 `Agent` 連線至右側帶有斜線紋理、標示 `Shell + Files` 的紅色方框，外圍有虛線框。
2. 第二列：
- 左側 `User A` 與 `User C` 同時連線至中間的 `Agent + SQLite` 藍色方框。
- 中間 `Agent` 連線至右側的 `Shell + Files` 紅色方框。
3. 第三列：
- 左側 `User C` 獨立呈現。
- 中間為標示 `Sleeping` 的灰色方框，外圍有虛線框。
- 右側為標示 `Shell + Paused Files` 的灰色方框，外圍有虛線框，兩者之間有連線。
展開畫面重點
畫面為黑底白線的互動時序圖（Sequence Diagram），頂端包含三個參與者：
1. `User`
2. `Actor`
3. `Sandbox`
互動流程依時間順序如下：
- `User` 發送訊息至 `Actor`：`Create agent (creates actor)`。
- `Actor` 發送訊息至 `Sandbox`：`Create sandbox`。
- `User` 發送訊息至 `Actor`：`Send prompt`。
- `Actor` 進入處理區塊（以藍色虛線外框標示，標註為 `Process prompt & run tools`）：
- `Actor` 與 `Sandbox` 之間進行兩次 `Tool call` 互動（包含發送請求與虛線回應）。
- `Actor` 發回回應至 `User`：`Response`（以向左的虛線箭頭表示）。
展開畫面重點
畫面為一段 TypeScript 程式碼，內容如下：
import { docker } from "@computesdk/docker";
import { actor } from "rivetkit";
// The same Docker provider setup as the simple example
const compute = docker({
runtime: "node",
image: { name: "node:22-slim", pullPolicy: "ifNotPresent" },
});
export const codingAgent = actor({
// The sandbox id is persisted so the actor can reattach to the same
// sandbox across sleeps and restarts
state: { sandboxId: null as string | null },
// Attach the sandbox when the actor wakes
createVars: async (c) => {
// Reattach to this session's sandbox, or boot a new one on first wake
let sandbox = c.state.sandboxId
? await compute.sandbox.getById(c.state.sandboxId)
: null;
if (!sandbox) {
sandbox = await compute.sandbox.create();
c.state.sandboxId = sandbox.sandboxId;
}
return { sandbox, tools: createTools(sandbox) };
},
// ...the rest of the actor comes together in step 5
});
這段程式碼主要展示了：
1. 從 `@computesdk/docker` 引入 `docker`，並從 `rivetkit` 引入 `actor`。
2. 透過 `docker()` 建立執行環境設定 `compute`，指定 runtime 為 `node`，以及 `node:22-slim` 映像檔。
3. 導出 `codingAgent` actor，內含 `state` 用於保存 `sandboxId`，並透過 `createVars` 函數在 actor 喚醒時重新連線至現有的 sandbox，若不存在則建立新的 sandbox，最後回傳 `sandbox` 與 `tools`。
展開畫面重點
畫面為一段深色主題的 TypeScript 程式碼，內容如下：
import { tool } from "ai";
import { z } from "zod";
// The agent's tools run in the actor. The sandbox only receives the
// commands and file operations that the tools send to it.
function createTools(sandbox: Sandbox) {
return {
runCommand: tool({
description: "Run a shell command in the sandbox",
inputSchema: z.object({ command: z.string() }),
execute: async ({ command }) => await sandbox.runCommand(command),
}),
// ... same writeFile and readFile tools as the simple example above
};
}
程式碼重點解析：
1. 引入了 `"ai"` 套件的 `tool` 函式以及 `"zod"` 套件的 `z`。
2. 註解說明 agent 的工具是在 actor 中執行，sandbox 只接收工具傳送過來的指令與檔案操作。
3. 定義 `createTools` 函式，接收 `sandbox: Sandbox` 參數，並回傳一個包含 `runCommand` 的物件。
4. `runCommand` 工具透過 `zod` 定義輸入結構（`inputSchema`）接收 `command` 字串，並在 `execute` 非同步函式中呼叫 `sandbox.runCommand(command)` 執行指令。
展開畫面重點
畫面為一段 JavaScript 程式碼，展示如何使用 `actor` 從 `"rivetkit"` 建立名為 `codingAgent` 的物件。
程式碼重點包含：
- 引入 `@ai-sdk/anthropic` 的 `anthropic`、`ai` 的 `generateText` 與 `stepCountIs`、以及 `"rivetkit"` 與 `"rivetkit/db"`。
- 設定 SQLite 資料庫，利用 `onMigrate` 執行 `db.execute` 建立 `messages` 資料表。
- 設定 `queues` 接收 `prompt` 任務。
- 在 `run` 函式中非同步處理佇列訊息，包含從 SQLite 載入 session history、執行 agent loop（呼叫 `generateText` 並指定 model 為 `anthropic("claude-sonnet-5")`、tools、`stopWhen: stepCountIs(20)`）、將訊息寫回資料庫，以及透過 `message.complete` 回覆結果。
展開畫面重點
畫面為深色背景的程式碼編輯器介面，內容如下：
import { setup } from "rivetkit";
import { codingAgent } from "./actors";
export const registry = setup({ use: { codingAgent } });
registry.start();
這段程式碼從 `rivetkit` 匯入 `setup` 函數，從 `./actors` 匯入 `codingAgent`，透過 `setup` 進行初始化並指定使用的 agent，最後呼叫 `registry.start()` 來啟動該註冊表。
展開畫面重點
畫面為一段 TypeScript 程式碼片段，深色背景，程式碼內容如下：
import { createClient } from "rivetkit/client";
import type { registry } from "./actors";
const client = createClient<typeof registry>();
// Each key is an independent agent with its own actor, sandbox, and history
const agent = client.codingAgent.getOrCreate(["demo"]);
程式碼透過 `rivetkit/client` 匯入 `createClient`，並從 `./actors` 匯入型別 `registry`，接著初始化 `client`，並透過註解說明每個鍵值都是具備各自 actor、sandbox 與 history 的獨立 agent，最後使用 `client.codingAgent.getOrCreate(["demo"])` 取得或建立名為 `"demo"` 的 agent 執行個體。
展開畫面重點
畫面為一段 JavaScript 程式碼，背景為深色。程式碼內容如下：
import * as readline from "node:readline/promises";
// Read tasks from the terminal and run the agent on each one
const terminal = readline.createInterface({
input: process.stdin,
output: process.stdout,
});
while (true) {
// Queue the task on the actor and wait for the agent to complete it
const prompt = await terminal.question("agent> ");
const result = await agent.send("prompt", { content: prompt }, { wait: true });
if (!result.response) throw new Error(`Task ${result.status}`);
console.log(result.response.text);
}
程式碼解析：
1. 載入 `node:readline/promises` 模組，透過 `process.stdin` 與 `process.stdout` 建立終端介面。
2. 進入無限迴圈 (`while (true)`)，使用 `terminal.question("agent> ")` 讀取終端機輸入的 prompt。
3. 將取得的 prompt 透過 `agent.send` 送出，並設定 `{ wait: true }` 等待 agent 完成任務。
4. 檢查回傳的 `result.response`，若無回應則拋出錯誤；若有回應則將結果文字印出。