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 viaspace("Name", { ephemeral: true }). Shares the identity's authenticated session and proxy without affecting your open tabs, and closes cleanly onfinish({ 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 skill | Print the version-matched agent guide negotiated with the running browser. |
isobay identities | List isolated identities, proxy modes, and primary Space IDs. |
isobay spaces list | claim | takeover | handoff | finish | List Spaces, transfer Human/AI control, or clean up finished tasks. |
isobay permissions list | grant | deny | reset | Inspect and configure per-Profile, per-Origin browser permissions. |
isobay mcp | Start 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 | — | OK | Completed cleanly. |
1 | -32603 | ERROR | General runtime or parameter error. |
2 | -32010 | SPACE_USER_IN_CONTROL | Hard stop. Human owns or took over the Space, or a permission/passkey prompt requires human action. Agents must stop without retrying. |
3 | -32020 | SPACE_CDP_BLOCKED | Blocked by built-in isolation and stealth guardrails. |
4 | -32030 | SPACE_SKILL_STALE | CLI 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(), ands.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, andpage.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.clipboardis isolated per Space so parallel agents never touch your system clipboard. - Files, Downloads & Frames: Headless
page.waitForFileChooser, nativepage.dropFiles, isolatedpage.waitForDownload, cross-originpage.frame(matcher), passivepage.waitForResponse, andpage.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