Bonsai
Documentation pages
Concepts
Documentation

Connecting your computer

A runtime is a computer of yours that does the work Bonsai sends it: chats beside a note, issue runs, Explain in the Inbox. Bonsai doesn’t run agents itself and never connects to your computer. The runtime connects out to Bonsai, takes runs, starts the official harness on your machine (Claude Code or Codex), and sends the session back.

With Bonsai for Mac

  1. Install Bonsai for Mac and open it. Its window is the Bonsai web workspace.
  2. Sign in inside the window.

As soon as the workspace loads, the app registers the Mac as a runtime under its own name (System Settings › General › About). If you already have a runtime with that name, the new one gets ” 2”. The runtime starts, and your personal space is enabled on it with all projects on this machine.

  1. Tell it where your code is: in Set Up This Mac…, under Folders, click Add Folder… and pick the folders that hold your repositories. Until you add one, the runtime has no projects.

Set Up This Mac… in the menu shows the four parts: the connection, the runtime, the agents (whether claude and codex were found, with install commands if not) and the folders Bonsai may use.

The app tries to connect by itself once per launch. If that doesn’t work, the menu says why; Connect this Mac… tries again, and opens the confirmation page instead when the window isn’t signed in.

With the command line

On a Mac without the app, or one you reach over SSH:

bonsai login           # shows a code and opens the confirmation page
bonsai daemon start    # keeps the runtime running under launchd
bonsai folders add ~/code   # the folders that hold your repositories

The confirmation page shows the machine’s name and a code. Approve only if you just ran bonsai login yourself and the terminal shows the same code. Someone else’s link would make their machine a runtime in your account.

bonsai login --no-browser prints the link instead of opening it. For a machine that can’t use a browser at all, add a runtime on the Runtimes page; it shows three lines (BONSAI_RUNTIME_URL, BONSAI_RUNTIME_ID, BONSAI_RUNTIME_TOKEN) once, which you paste into bonsai login --paste.

The app and the command line share ~/.bonsai, so a machine paired either way works with both. bonsai status shows where things stand.

What the connection carries

  • Credentials. A runtime ID and a token, generated by Bonsai when you pair and handed out once. Bonsai keeps only the token’s SHA-256. On your computer they live in ~/.bonsai/bonsai-runtime.toml, readable only by you (0600). They never go into logs, launchd plists, command-line arguments, or the environment of agents the runtime starts.
  • One outbound WebSocket. wss://livewithbonsai.com/runtime, with the token in the Authorization header. The first message lists the harnesses, models and settings on the machine, and its projects: each as an ID and a git remote such as github.com/you/app. No local path leaves your computer.
  • Heartbeat and reconnects. A ping every 25 seconds. After 60 seconds without an answer, or a network drop, the runtime reconnects with backoff, from 1 second doubling up to 1 minute.

Which folders it works in

Only in folders you add. There are none at first, and the runtime never scans your whole home folder on its own. Add them in the setup window with Add Folder… (pick several at once if you like: a repository, or a folder that holds many), or with bonsai folders add <path>. Each folder has a Remove button, and bonsai folders remove <path> does the same; projects found only in that folder go away. bonsai folders lists them.

In those folders, the runtime looks for git repositories with a remote when it starts and every 10 minutes, and offers them as this machine’s projects: up to 5 levels deep, at most 150, most recently used first. Hidden folders, node_modules, target, Library and media folders are skipped. A project you remove with bonsai project remove isn’t added back by the next scan; adding its folder again brings it back.

To register a single folder as a project without a scan, use Register Folder… in the menu or bonsai project add <path>.

A note can name the repository it’s about, but it can’t point the runtime at a folder: paths come only from your own machine.

Your personal space can use every project on the machine from the start. To let another space you belong to use the runtime, enable it on the Runtimes page and choose which projects that space may use.

Removing a runtime

Delete it on the Runtimes page. Its token stops working at once: Bonsai cancels its runs and closes the connection, and the runtime stops the sessions Bonsai started and doesn’t reconnect.

Bonsai for Mac won’t register the Mac again on its own after that. The menu and the setup window say the Mac was deleted and offer Connect this Mac…. From the command line, run bonsai login --force.