3. Connect the agent

The daemon reaches your web app through the supabaseBridge extension. It authenticates with a personal access token (PAT): you mint it, it is scoped to you, you can revoke it from the web UI, and the agent exchanges it for a short-lived JWT instead of holding a long-lived key.

Let `boba init` wire it

Mint a token

Open the web app, sign in, and create a token at /auth/token.

Run the wizard


boba init

Pick Background service, then Connect at Connect to a Boba web app?. Enter the web app’s URL, paste the token, and name the agent (the default is this machine’s host name).

The wizard runs the same token exchange the daemon will, before it writes anything. It tells you whether the URL or the token was the problem and asks for that one again. If the web itself is broken (it can’t sign a token, or isn’t answering), you can write the config anyway, enter a different URL, or skip.

If BOTBANDIT_WEB_URL or BOTBANDIT_PAT is set in your environment, the wizard offers it, and the config then references the variable instead of the value. A pasted token is written into the config file, which only you can read.

boba init only runs on a machine with no config yet. If you already have one, move it aside and re-run, or edit it by hand.

By hand

This is what the wizard writes:


service:
  enabled: true
 
profiles:
  claude:
    # …provider and model…
    extensions: [approval, memory, supabaseBridge]  # append to the existing list
 
extensions:
  supabaseBridge:
    agentName: "my-laptop"
    url: https://your-web-host      # BASE url only, no path
    pat: env:BOTBANDIT_PAT          # or plain:pat_… / a bare literal
    # syncDocuments: false          # turns off the two-way sync of ~/.botbandit/docs with the web

Then restart the daemon:


boba daemon restart

Secrets accept three forms anywhere in the config: env:NAME, plain:value, or a bare literal (treated as plain). Prefer env:.

Four things the wizard does for you. Missing any of them doesn’t fail at startup. The agent just never shows up on the web. The first two leave no trace at all, and the last two only show up in ~/.botbandit/daemon.log.

service.enabled: true. The bridge only runs inside the daemon. In in-process mode it never starts.
supabaseBridge on every profile, including the default one. A session mirrors only if its own profile lists the bridge. The daemon starts presence and document sync from the default profile’s extensions.
url is the site root, not the token page. The bridge appends /api/auth/access-token itself. If you paste /auth/token (the page you minted the PAT on), the exchange POSTs to /auth/token/api/auth/access-token and gets a 404.
localhost means this machine. url: http://localhost:3000 works only where the web app runs. On a second machine, use an address that machine can reach.

Direct credentials

The setup script also prints an AGENT / CLI block with direct Supabase credentials (supabaseUrl + apiKey). They also need a user JWT from a web login, so use the PAT path above instead: only it supports push notifications and the remote terminal.

What the bridge does

Once connected, the daemon:

publishes session events so the web UI can render live transcripts,
subscribes to your private realtime channel for commands from the browser (new sessions, approvals, terminal input),
syncs the document vault to Postgres, so notes and tasks are editable from either side,
offloads image bytes to the images bucket instead of broadcasting them.

All of it over private:{userId} channels that only you can join.

Next: verify the whole chain.