InstaBox 浏览器控制教程

用一台云端 Linux 机器 + 浏览器，让 AI Agent 像人一样操作网页。
本文聚焦 如何用 InstaBox 的 Computer Use / Desktop 功能启动、打开并控制浏览器。

1. 前置准备

1.1 获取 API Key

在 InstaBox 控制台的 API Keys 页面创建，或使用 CLI：

npx instabox@latest keys create

1.2 配置环境变量

export INSTABOX_API_KEY=你的_key
export INSTABOX_API_URL=https://api.instabox.sh   # 可选，这是默认值

1.3 安装 SDK

npm install @insforge/instabox-sdk

关键概念：agent-browser 模板
Sandbox.create() 默认使用 agent-browser 模板——它预装了 Xfce 桌面和 Chromium 浏览器（显示在 :1）。控制浏览器的所有能力都来自这个"桌面"。

2. 创建带浏览器的机器

import { Sandbox } from '@insforge/instabox-sdk'

const sandbox = await Sandbox.create()   // 默认 agent-browser 模板，自带桌面 + 浏览器
console.log(sandbox.sandboxId)           // 形如 m_...

可选参数（按需添加）：

const sandbox = await Sandbox.create({
  name: 'my-browser-box',            // 名称：小写字母/数字/-
  metadata: { userId: 'u_42' },      // 标签，用于定位这台机器
  autoSuspendMs: 0,                  // 0 = 永不自动暂停（避免干活时被打断）
  timeoutMs: 30 * 60_000,            // 30 分钟后自动暂停（60s ~ 24h）
})

• 也可以用快照/模板 ID：Sandbox.create('my-setup') 或 Sandbox.create('sn_...')
• create 会等待创建操作完成；sandbox.getInfo() 可查 runtime.ready 确认就绪

3. 启动桌面

浏览器跑在虚拟桌面上，所以第一步是启动桌面：

const info = await sandbox.desktop.start()
// { installed, running, width: 1280, height: 800 }

• 已在运行则为 no-op，可放心重复调用
• 可自定义分辨率（宽 800–2560，高 600–1600）：

await sandbox.desktop.start({ width: 1920, height: 1080 })

• 非 agent-browser 模板会先自动安装桌面，首次约需半分钟

4. 在浏览器里打开网址

await sandbox.desktop.open('https://example.com')

open() 会在 Chromium 中打开指定网址。之后就可以用下面第 5 节的操作来驱动它了。

注意：打开前确保机器处于运行态。若暂停了，先 await Sandbox.connect(sandbox.sandboxId) 恢复。

5. 控制浏览器：完整操作清单

所有坐标均为屏幕像素，左上角为 (0,0)。

5.1 截图（看当前页面）

const png = await sandbox.desktop.screenshot()   // 返回 Uint8Array，PNG 格式
// 保存到本地：
const { writeFileSync } = await import('node:fs')
writeFileSync('page.png', png)

5.2 点击

await sandbox.desktop.click(640, 400)                                 // 左键单击
await sandbox.desktop.click(640, 400, { button: 'right' })            // 右键
await sandbox.desktop.click(640, 400, { button: 'left', double: true }) // 双击

5.3 移动鼠标 / 拖拽

await sandbox.desktop.move(100, 200)                        // 移动到坐标
await sandbox.desktop.drag([100, 200], [300, 400])          // 从 A 拖到 B

5.4 滚动

await sandbox.desktop.scroll({ direction: 'down', amount: 3 })
await sandbox.desktop.scroll({ direction: 'up', amount: 1 })

5.5 输入文本

await sandbox.desktop.type('Hello world ✓\n')   // 原样输入，含换行（回车）

文本通过 stdin 送入，支持中文、emoji 等 UTF-8 字符。

5.6 按键 / 组合键

await sandbox.desktop.press('Enter')                // 单个键
await sandbox.desktop.press(['ctrl', 'l'])          // 组合键（定位地址栏）
await sandbox.desktop.press(['ctrl', 'w'])          // 关闭标签页

常用键名：Enter、Esc、Tab、Backspace、方向键、F1–F24、ctrl、alt、shift、cmd；也支持 X keysym 名称。

5.7 查询鼠标位置

const { x, y } = await sandbox.desktop.cursorPosition()

6. 实战示例：自动化搜索一个关键词

完整流程：打开 Google → 截图 → 点击搜索框 → 输入关键词 → 回车 → 截图结果。

import { Sandbox } from '@insforge/instabox-sdk'
import { writeFileSync } from 'node:fs'

async function main() {
  // 1. 建机器并启动桌面
  const sandbox = await Sandbox.create({ autoSuspendMs: 0 })
  await sandbox.desktop.start({ width: 1280, height: 800 })

  // 2. 打开目标站点
  await sandbox.desktop.open('https://www.google.com')
  await sleep(2500)   // 等页面加载
  writeFileSync('step1_home.png', await sandbox.desktop.screenshot())

  // 3. 点击搜索框（坐标需按截图确认）
  await sandbox.desktop.click(400, 350)

  // 4. 输入关键词并回车
  await sandbox.desktop.type('InstaBox browser automation')
  await sandbox.desktop.press('Enter')
  await sleep(3000)

  // 5. 截图结果页
  writeFileSync('step2_results.png', await sandbox.desktop.screenshot())

  // 6. 收尾（按需：暂停或删除）
  await sandbox.pause()      // 暂停省钱，稍后可恢复
  // await sandbox.kill()    // 或直接删除
}

function sleep(ms: number) { return new Promise(r => setTimeout(r, ms)) }

main().catch(console.error)

提示：type 到 press('Enter') 这类"找坐标"的操作，正确姿势是 截图 → 人工/视觉模型确认元素坐标 → 再点击。真实 Agent 常配合视觉模型看截图来定位。

7. 人类实时查看 / 接管浏览器画面

生成一个可分享的实时桌面链接，放进 iframe 或直接打开：

const { url, expiresAt } = await sandbox.desktop.streamUrl({
  viewOnly: true,        // true = 只读观看；false = 观看者也能用鼠标键盘
  ttlSeconds: 3600,      // 有效期：60s ~ 24h，默认 1h
})
console.log(url)         // 打开即看到浏览器画面，无需 instabox 账号

• 链接到期停止新连接；到期前已连上的 viewer 会一直看到离开
• 主动结束访问：

await sandbox.desktop.revokeStreamUrls()   // 作废所有链接，几秒内断开观看者

关键前提：链接打开时机器必须处于 running 状态（暂停的机器不会因链接被唤醒），发链接前先 connect()：

const box = await Sandbox.connect(sandbox.sandboxId)  // 若暂停则自动恢复
await box.desktop.start()
const { url } = await box.desktop.streamUrl({ viewOnly: false })

8. 关闭与清理

await sandbox.pause()   // 暂停：停止计费，之后可恢复
await sandbox.kill()    // 删除机器，释放资源

• 暂停/恢复：Sandbox.connect(id) 会在暂停时自动恢复；kill() 删除
• 用量与账单查询：Sandbox.getUsage(sandbox.sandboxId)、Sandbox.usage()

9. 注意事项与常见坑

附：常见问题速查

Q：打开浏览器提示桌面未运行？
A：先 await sandbox.desktop.start()，确认 running: true 再 open()。

Q：暂停后 open() 失败？
A：先 await Sandbox.connect(sandboxId) 恢复运行，再启动桌面。

Q：想让人只能看、不能操作？
A：streamUrl({ viewOnly: true })。

Q：想关掉所有观看链接？
A：await sandbox.desktop.revokeStreamUrls()。

Q：不用 SDK，纯命令行能做吗？
A：可以。CLI：npx instabox@latest sh 进 shell 后，用 xdotool / scrot 或直接跑 Chromium；REST 端点与 SDK 一一对应，见官方 /docs/api。