Bonsai
文档目录
概念
文档

连接你的电脑

执行端（runtime）是你自己的一台电脑，负责做 Bonsai 派来的活：笔记旁边的对话、issue 的 run、收件箱里的「解释」。Bonsai 自己不跑 agent，也从不连你的电脑：执行端主动连到 Bonsai，接下 run，在你的电脑上启动官方 harness（Claude Code 或 Codex），再把会话传回来。

用 Bonsai for Mac

  1. 安装并打开 Bonsai for Mac。窗口里就是 Bonsai 的网页工作区。
  2. 在窗口里登录。

工作区一加载出来，app 就用这台 Mac 自己的名字（系统设置 › 通用 › 关于本机）把它注册成执行端；你已经有同名的执行端时，新的这台名字后面加「 2」。执行端随即启动，你的个人空间也同时启用了它，开放「这台机器上的全部项目」。

  1. 告诉它你的代码在哪：在「设置这台 Mac…」的「文件夹」里点「添加文件夹…」，选装着你的仓库的文件夹。一个都没添加之前，执行端没有项目。

菜单里的「设置这台 Mac…」列出四部分：连接、执行端、agent（找没找到 claude 和 codex，没找到给安装命令）、Bonsai 可以用的文件夹。

app 每次启动最多自动连接一次。没成功的话菜单里会写原因；点「连接这台 Mac…」再试一次，窗口没登录时会改为打开确认页。

用命令行

在没装 app 的 Mac 上，或者通过 SSH 连着的机器上：

bonsai login           # 显示一个码，并打开确认页
bonsai daemon start    # 交给 launchd，让执行端一直运行
bonsai folders add ~/code   # 装着你的仓库的文件夹

确认页上显示机器名和一个码。**只在你自己刚刚运行了 bonsai login、终端上显示的也是这个码时才确认。**确认了别人发来的链接，他的机器就成了你名下的执行端。

bonsai login --no-browser 只打印链接，不打开浏览器。完全用不了浏览器的机器，可以在执行端页面上添加一台：页面只显示一次三行配置（BONSAI_RUNTIME_URL、BONSAI_RUNTIME_ID、BONSAI_RUNTIME_TOKEN），贴给 bonsai login --paste。

app 和命令行共用 ~/.bonsai，用哪种方式配对的机器，两边都能用。bonsai status 看当前状态。

连接里有什么

  • 凭据：一个 runtime ID 和一枚 token，配对时由 Bonsai 生成，只给一次；Bonsai 只存 token 的 SHA-256。在你的电脑上，它们放在 ~/.bonsai/bonsai-runtime.toml，只有你自己能读（0600）。它们不会进日志、launchd 的 plist、命令行参数，也不会进执行端拉起的 agent 的环境变量。
  • 一条往外的 WebSocket：wss://livewithbonsai.com/runtime，token 放在 Authorization 请求头里。第一条消息列出这台机器上的 harness、模型和设定，以及它的项目：每个项目是一个 ID 加一个 git remote（比如 github.com/you/app）。本机路径不会离开你的电脑。
  • 心跳与重连：每 25 秒一次 ping。60 秒没有回应，或者网络断了，执行端就按退避重连：从 1 秒开始翻倍，最长 1 分钟。

能在哪些文件夹里干活

只在你添加的文件夹里。一开始一个都没有，执行端也不会自己去扫整个家目录。在设置窗口里点「添加文件夹…」（可以一次选好几个：一个仓库，或者装着很多仓库的上层文件夹），或者运行 bonsai folders add <路径>。每个文件夹旁边有「移除」，bonsai folders remove <路径> 也一样；只在那个文件夹里找到的项目随之移除。bonsai folders 列出现在有哪些。

在这些文件夹里，执行端启动时和之后每 10 分钟找一遍带 remote 的 git 仓库，当作这台机器的项目：最深 5 层，最多 150 个，最近用过的优先；跳过隐藏文件夹、node_modules、target、Library 和媒体文件夹。用 bonsai project remove 移除的项目，下次扫描不会再加回来；重新添加它所在的文件夹就回来了。

不扫描、只把一个文件夹登记成项目，用菜单里的「登记文件夹…」或 bonsai project add <路径>。

笔记可以写它对应哪个仓库，但没法让执行端指向某个文件夹：路径只来自你自己的电脑。

你的个人空间一开始就能用这台机器上的全部项目。想让你加入的其他空间也用这台执行端，在执行端页面上启用它，并选好那个空间能用哪些项目。

删除执行端

在执行端页面上删除它。它的 token 立刻失效：Bonsai 取消它手上的 run 并关掉连接，执行端停掉 Bonsai 开的会话，不再重连。

之后 Bonsai for Mac 不会自己把这台 Mac 再注册回去。菜单和设置窗口会写明这台 Mac 已被删除，并给出「连接这台 Mac…」。命令行里运行 bonsai login --force。