Function Compute：使用 Computer Use Sandbox

如果任務只需要訪問網頁、點擊、填表、截圖或抓取動態網頁面，優先使用 Browser Use Sandbox，通過 CDP 精確控制瀏覽器。只有當任務必須操作瀏覽器以外的案頭應用，或必須以“像素座標 + 截圖”的視覺方式驅動介面時，才選擇 Computer Use Sandbox。

適用情境

與 Browser Use Sandbox 的區別

準備工作

1. 按照 Desktop 模板 構建模板，例如 my-desktop-template。

2. 配置與模板同地區的 E2B_API_KEY、E2B_API_URL 和 E2B_DOMAIN（SDK 自動讀取）。

3. 安裝對應語言的 Desktop SDK，安裝命令與依賴版本見 Desktop 模板。

Python 樣本

以下樣本建立案頭沙箱，啟動 Chrome，完成截圖和滑鼠鍵盤操作，並開啟帶鑒權的即時資料流。

"""Computer Use Sandbox 樣本。"""

import os

from dotenv import load_dotenv
from e2b_desktop import Sandbox

load_dotenv()

TEMPLATE = os.environ.get("E2B_DESKTOP_TEMPLATE", "my-desktop-template")

desktop = None
try:
    # timeout 單位為秒，需覆蓋案頭冷啟動與任務全過程。
    desktop = Sandbox.create(template=TEMPLATE, timeout=600)

    # 啟動 Chrome，並等待視窗渲染完成；wait 單位為毫秒。
    desktop.launch("google-chrome", "https://example.com")
    desktop.wait(10000)

    # 滑鼠操作。
    desktop.move_mouse(640, 400)
    desktop.left_click()
    desktop.double_click()
    desktop.scroll("down", 5)

    # 在終端中輸入命令，驗證鍵盤和按鍵組合操作。
    desktop.launch("xfce4-terminal")
    desktop.wait(3000)
    desktop.write("computer use")
    desktop.press(["ctrl", "a"])
    desktop.write("echo ")
    desktop.press("enter")
    desktop.wait(1000)

    # 截圖返回 PNG 位元組，可交給視覺模型或儲存到檔案。
    image = desktop.screenshot()
    with open("desktop.png", "wb") as f:
        f.write(image)

    # 開啟帶 VNC 口令的即時資料流。
    desktop.stream.start(require_auth=True)
    auth_key = desktop.stream.get_auth_key()
    stream_url = desktop.stream.get_url(auth_key=auth_key)
    # 將 stream_url 交給受控後端使用，不要寫入公開日誌。

    # 在此執行 Agent 的“截圖 -> 決策 -> 操作”迴圈。

    desktop.stream.stop()
finally:
    if desktop is not None:
        desktop.kill()

TypeScript 樣本

將以下代碼儲存為 computer-use.ts：

import "dotenv/config";
import { writeFileSync } from "node:fs";
import { Sandbox } from "@e2b/desktop";

const TEMPLATE = process.env.E2B_DESKTOP_TEMPLATE ?? "my-desktop-template";

let desktop: Sandbox | undefined;
try {
  // timeoutMs 單位為毫秒，需覆蓋案頭冷啟動與任務全過程。
  desktop = await Sandbox.create(TEMPLATE, { timeoutMs: 600_000 });

  await desktop.launch("google-chrome", "https://example.com");
  // 等待應用視窗渲染完成，避免截到尚未載入的案頭。
  await desktop.wait(10_000);

  await desktop.moveMouse(640, 400);
  await desktop.leftClick();
  await desktop.doubleClick();
  await desktop.scroll("down", 5);

  await desktop.launch("xfce4-terminal");
  await desktop.wait(3_000);
  await desktop.write("computer use");
  await desktop.press(["ctrl", "a"]);
  await desktop.write("echo ");
  await desktop.press("enter");
  await desktop.wait(1_000);

  const image = await desktop.screenshot();
  writeFileSync("desktop.png", image);

  await desktop.stream.start({ requireAuth: true });
  const authKey = desktop.stream.getAuthKey();
  const streamUrl = desktop.stream.getUrl({ authKey });
  // 將 streamUrl 交給受控後端使用，不要寫入公開日誌。

  // 在此執行 Agent 的“截圖 -> 決策 -> 操作”迴圈。

  await desktop.stream.stop();
} finally {
  await desktop?.kill();
}

運行樣本：

npm install
npx tsx computer-use.ts

Desktop 模板能力及 Python、TypeScript 常用 API 對照見 Desktop 模板。

即時資料流與鑒權

• stream.start(require_auth=True) / stream.start({ requireAuth: true }) 會為 VNC 流產生訪問口令。

• get_auth_key() / getAuthKey() 必須在啟用 require_auth / requireAuth 後調用，否則 SDK 會拋出錯誤。

• stream.get_url() 返回 noVNC 地址。唯讀觀察可使用 Python view_only=True 或 TypeScript viewOnly: true。

• 同一時刻只能開啟一個流。v0.0.44 版本支援整案頭流，暫不支援指定單個視窗。

通過Function Compute公網網關訪問 /vnc.html 和 /websockify 時，還需要沙箱的 X-Access-Token。require_auth 產生的 auth_key 是 VNC 流自身的訪問口令，兩者是獨立的兩層鑒權。普通瀏覽器無法為頁面和 WebSocket 任意附加要求標頭，面向終端使用者提供即時查看時，建議由業務後端通過受控反向 Proxy注入 X-Access-Token，不要把沙箱 Token 暴露到前端或公開日誌。

安全與上線建議

• 憑證隔離：模型 Key、帳號密碼和業務 Token 通過運行時環境變數注入，不要寫入模板鏡像。

• 流存取控制：即時資料流開啟 require_auth，唯讀示範情境使用 view_only，不要把帶口令的 URL 寫入公開日誌。

• 防提示注入：不要讓 Agent 未經校正地把螢幕文字當作系統指令執行；提交、刪除、支付等敏感操作應設定人工確認。

• 資源與生命週期：為任務設定合理逾時，並始終在 finally 中調用 kill()。

• 動作審計：記錄必要的截圖、滑鼠座標、按鍵序列和目標視窗，便於複現與追蹤。

• 最小許可權：限制沙箱可訪問的網域名稱、可開機應用和可寫目錄。

相關文檔

• Desktop 模板

• Browser Use Sandbox

• AIO Sandbox

• 上傳和下載檔案