/share-server-links

name: share-server-links
description: "Expose a local HTTP server through BB Connect and give the user its remotely accessible URL."

Share local server links via bb connect

When you start an HTTP server the user should open, give them a connect share URL — not a localhost URL. Shares work from threads running on any enrolled host, and the command resolves the thread's host automatically.

1. Check remote access: run `bb connect status --json`. If `paired` is false, give the localhost URL and mention that remote URLs work once this bb is signed in to its bb account (`bb account login`). If `enabled` is false, the user turned remote access off with `bb connect off`; give the localhost URL and mention `bb connect on`. Don't turn it on or sign in yourself unless the user asks. 2. From the thread that started the HTTP server, run `bb connect expose <port>`. It prints that host's share URL. Use `--host <name-or-id>` only when you intentionally need another enrolled host; outside a thread, sharing defaults to the machine running the bb server. 3. Give the returned URL to the user as a markdown link. It works for viewers who have the owner's getbb.app session; it is not a public internet link. 4. When the server stops, run `bb connect unexpose <port>` from the same thread (or with the same `--host`) so the share is cleaned up. Use `bb connect shares [--host <name-or-id>]` to inspect that host's shares.

Use `bb connect unexpose-all [--host <id>] [--json]` to revoke all shared ports on one machine, including an unavailable machine. It defaults to the thread's machine, or the server machine outside a thread, and keeps machine pairing intact. Each collapsible machine group in settings offers **Revoke all** for that machine. The typed plugin RPC is `unexposeAll` with `{ hostId: string }` input and a `{ removed: number }` result. Bulk revocation attempts every share on that machine; any failures report partial progress and can be retried.

`bb connect --help` and `bb connect <command> --help` print the commands and their flags and exit 0. Unknown commands and flags fail with a suggestion — `bb connect list` points at `bb connect shares` — and with `--json` a failure prints `{"ok":false,"error":{"code":…,"message":…}}` on stdout while the same message stays on stderr.

Server-host shares use `https://<server-label>--<port>.<base-domain>` through the server tunnel. Other enrolled hosts use `https://<machine-label>--<port>.<base-domain>` through their daemon. If a machine was not enrolled through Connect, expose fails with instructions to remove and re-add it under Settings > Machines.

Remote access and the bb account

Remote access runs through the bb account plugin, which holds the getbb.app pairing. `bb connect off` turns remote access off and keeps the account signed in; `bb connect on` turns it back on. Both set the connect `remoteAccess` setting (`bb plugin config connect set remoteAccess false`). `bb account logout` forgets the pairing, and `bb account status` shows which account is signed in. `bb connect --code <code>` still pairs with a dashboard code like `bb account login --code <code>`, and also turns remote access back on if it was off. `--server` takes the dashboard's `https://<handle>.getbb.app` (or `https://<handle>.vibecodethis.site`) URL; other origins are refused.

Agent instructions setting

Settings → Installed plugins → Connect has a "Tell agents about remote access" toggle, enabled by default. Use `bb plugin config connect set sendRemoteInstructions false` to suppress the remote-access message, or `true` to restore it. This controls only the message; sharing still works. The message otherwise requires active or recent remote usage. Changes apply when session instructions are next assembled.