Documentation

Architecture overview, CLI commands and exit codes, SDK guide, permissions model, and MCP setup.

Workspaces & Profile Isolation

Each Isobay identity is backed by its own isolated Chromium profile directory with separate cookies, storage, cache, history, extensions, downloads, proxy settings, and consistent same-OS hardware parameters.

  • Primary Space (kind: "primary"): The persistent default workspace for an identity. Idle profiles hibernate automatically and reload on demand.
  • Ephemeral Task Space (kind: "ephemeral"): Created on demand for automation via space("Name", { ephemeral: true }). Shares the identity's authenticated session and proxy without affecting your open tabs, and closes cleanly on finish({ keep: [] }).
  • Single-Window Frame: Switch instantaneously between workspaces inside one desktop window on macOS (app.isobay.browser), Windows (Isobay.Browser), and Linux (app.isobay.Browser), or detach any workspace into its own standalone window.

工作区与 Profile 隔离

Isobay 中的每个身份都对应独立的浏览器 Profile 目录,Cookie、本地存储、缓存、历史记录、扩展、下载、代理配置以及同系统设备参数完全隔离。

  • 主工作区(kind: "primary"):每个身份默认拥有的持久工作区,闲置时自动休眠释放内存,点击或调用时按需唤醒。
  • 临时任务工作区(kind: "ephemeral"):通过 space("名称", { ephemeral: true }) 按需创建,复用该身份的登录态与代理而不打扰您正在使用的标签页,finish({ keep: [] }) 后自动清理。
  • 单窗桌面框架:在 macOS(app.isobay.browser)、Windows(Isobay.Browser)与 Linux(app.isobay.Browser)上均支持单窗切换,也可将任意工作区弹出为独立窗口。

CLI & Exit Codes

The isobay CLI (with spaces compatibility alias) communicates directly with the running browser over local IPC with zero remote debugging ports.

CLI 命令与退出码

isobay CLI(兼容别名 spaces)通过受系统保护的本机 IPC 与浏览器通信,无需开启任何调试端口。

Command Purpose
isobay skillPrint the version-matched agent guide negotiated with the running browser.
isobay identitiesList isolated identities, proxy modes, and primary Space IDs.
isobay spaces list | claim | takeover | handoff | finishList Spaces, transfer Human/AI control, or clean up finished tasks.
isobay permissions list | grant | deny | resetInspect and configure per-Profile, per-Origin browser permissions.
isobay mcpStart the stdio JSON-RPC 2.0 MCP server.
isobay run [-e code | file | stdin]Execute an async script with @isobay/sdk helpers preloaded.

Exit Codes

Code RPC Symbol Meaning
0—OKCompleted cleanly.
1-32603ERRORGeneral runtime or parameter error.
2-32010SPACE_USER_IN_CONTROLHard stop. Human owns or took over the Space, or a permission/passkey prompt requires human action. Agents must stop without retrying.
3-32020SPACE_CDP_BLOCKEDBlocked by built-in isolation and stealth guardrails.
4-32030SPACE_SKILL_STALECLI is older than the running browser's minimum protocol version.

SDK (@isobay/sdk)

Zero-dependency client library compatible with Node 22.18+ and Bun:

  • Spaces & Ownership: client.space(name, { ephemeral }), s.claim(), s.takeOver(), s.handOff(reason), s.waitForControl(), and s.finish({ keep }). An atomic local ledger at ~/.isobay/state/ ensures user-opened tabs are never closed by automation.
  • Trusted Input & Canvas: page.mouse, page.keyboard, and page.canvas(selector?) emit native trusted events (isTrusted === true) with local and normalized [0..1] canvas coordinates plus visual change detection.
  • IME & Per-Space Clipboard: page.ime.compose() supports CJK editors natively; page.clipboard is isolated per Space so parallel agents never touch your system clipboard.
  • Files, Downloads & Frames: Headless page.waitForFileChooser, native page.dropFiles, isolated page.waitForDownload, cross-origin page.frame(matcher), passive page.waitForResponse, and page.pdf().

SDK(@isobay/sdk)

零第三方运行时依赖,兼容 Node 22.18+ 与 Bun:

  • 工作区与控制权:支持 client.space(name, { ephemeral })、s.claim()、s.takeOver()、s.handOff(reason)、s.waitForControl() 与 s.finish({ keep });~/.isobay/state/ 本地原子账本确保自动化绝不误关人工打开的标签页。
  • 原生可信输入与 Canvas:page.mouse、page.keyboard 与 page.canvas(selector?) 均触发原生可信事件(isTrusted === true),支持局部与归一化 [0..1] 坐标及画面稳定检测。
  • 中文 IME 与独立剪贴板:page.ime.compose() 原生适配中文富文本编辑器;page.clipboard 按工作区隔离,多任务并发绝不干扰系统剪贴板。
  • 文件、下载与跨域帧:支持无弹窗 page.waitForFileChooser、原生拖放 page.dropFiles、独立下载目录 page.waitForDownload、跨域 page.frame(matcher)、被动响应监听 page.waitForResponse 与 page.pdf()。

3-Tier Permissions Model

Browser permissions are enforced strictly per identity profile:

三层权限模型

所有浏览器权限均严格按身份 Profile 独立生效:

Tier Capabilities Behavior under AI
Tier 1
Virtualized Safe
geolocation, clipboard-read, clipboard-write, notifications, automatic-downloads Configurable per Space. Geolocation serves proxy exit region; clipboard uses the Space's isolated clipboard; downloads stay in the Space folder.
Tier 2
Profile + Origin
camera, microphone, display-capture, midi, sensors, local-fonts Defaults to prompting the user (pauses AI). Can be pre-granted strictly per identity and origin.
Tier 3
Human-Only
WebAuthn / Passkeys, OS keychain, USB, HID, Bluetooth, Serial, client certificates Never auto-granted. Always stops immediately with SPACE_USER_IN_CONTROL for human action.

MCP Server

Run isobay mcp to expose a stdio MCP server (protocolVersion 2024-11-05) with spaces_list, spaces_identities, spaces_run, spaces_handoff, spaces_finish, and spaces_permissions.

MCP Server

运行 isobay mcp 即可启动标准 stdio MCP 服务(protocolVersion 2024-11-05),提供 spaces_list、spaces_identities、spaces_run、spaces_handoff、spaces_finish 与 spaces_permissions 工具。

{
  "mcpServers": {
    "isobay": {
      "command": "isobay",
      "args": ["mcp"]
    }
  }
}

Local IPC & Early Access Setup

Isobay communicates strictly over private same-user local IPC (~/.isobay/run/bridge.sock on macOS, $XDG_RUNTIME_DIR/isobay/bridge.sock on Linux, and \\.\pipe\isobay-browser-<user> on Windows). Override paths with ISOBAY_IPC_PATH and ISOBAY_STATE_DIR.

To request Early Access builds, email preview@isobay.app.

本机 IPC 与早期体验配置

Isobay 仅通过当前系统用户私有的本机 IPC 通信(macOS 为 ~/.isobay/run/bridge.sock,Linux 为 $XDG_RUNTIME_DIR/isobay/bridge.sock,Windows 为 \\.\pipe\isobay-browser-<user>),可通过 ISOBAY_IPC_PATH 与 ISOBAY_STATE_DIR 自定义路径。

如需申请早期体验安装包,请发送邮件至 preview@isobay.app。

isobay --version
isobay skill | tail -n 5
isobay identities
isobay spaces list