Personal Tailscale access for bb

An independent embedded Tailscale node lets your own personal-tailnet devices reach this bb over HTTPS. Your Mac’s system Tailscale account stays separate. Remote access starts off.

Supported native target: macOS Apple silicon (darwin/arm64). Requires BB with Plugin SDK 0.6.79 or newer, a Tailscale account, and tailnet MagicDNS and HTTPS certificates. Linux, Windows, and Intel Mac binaries are not provided. The default hostname is bb-personal-<eight-character-id> and can be changed in Settings. HTTPS certificate records publicly include the chosen name.

Install on another BB instance

Run these commands on the Mac hosting the BB server you want to access. Install Git, Bun, Deno, and Go first, or use the Nix alternative below. Go automatically downloads the toolchain required by the pinned Tailscale module.

git clone https://git.yadunut.dev/yadunut/bb-tailscale.git
cd bb-tailscale
bun install --frozen-lockfile
deno run --allow-run --allow-read --allow-write --allow-env scripts/build-helper.ts
bb plugin build .
bb plugin install "$PWD"

For Nix users, replace the Bun and Deno commands with:

nix shell nixpkgs#bun -c bun install --frozen-lockfile
nix shell nixpkgs#deno -c deno run --allow-run --allow-read --allow-write --allow-env scripts/build-helper.ts

The build script uses installed Go or falls back to nix shell nixpkgs#go. Keep this checkout in place: BB registers the local path and uses its compiled helper. Go and Deno are build-time tools; the running plugin does not download executables. A bare bb plugin install https://git.yadunut.dev/yadunut/bb-tailscale does not build the native helper, so use the clone-and-build sequence above.

For multiple BB instances, run the install against each intended BB server using its own CLI connection. Each instance generates its own installation ID and Tailscale identity. Give them distinct hostnames. Do not copy node credentials between running instances.

Use

Open Settings → Tailscale (the Personal Tailscale section), or use the same controls from the CLI:

bb tailscale status --json
bb tailscale login
bb tailscale status
bb tailscale on
bb tailscale off
bb tailscale logout

To rename the embedded node, edit Hostname in Settings → Tailscale, or run:

bb tailscale hostname bb-studio
bb tailscale status --json

Use 1–63 lowercase letters, digits, or hyphens, starting and ending with a letter or digit. Enter a short hostname, not a URL or .ts.net domain. Saving while access is off only stores the name. When enabled, the rename waits for any pending sign-in or sign-out operation, then reconnects the helper and closes existing remote sessions. Check status until Tailscale reports the updated HTTPS address. It keeps the same saved node identity and does not require signing in again. Use the actual URL returned by status, since Tailscale may resolve name collisions with a suffix.

Login prepares the embedded node without enabling access when off. Choose your personal account in the sign-in link, then enable remote access. status shows any pending login, device approval, HTTPS setup error, or ready URL. On your phone, connect Tailscale to the same personal tailnet and open the HTTPS address in Safari, or enter it as a direct server URL in the bb phone app. This is separate from Connect pairing.

off immediately closes remote connections, terminates the helper and retains the node identity. logout first turns access off, then logs out only the embedded node. Logout while already off never opens an incoming listener. Reload, disable and bb shutdown stop the supervised helper; stdin EOF also stops it if bb exits abruptly.

The plugin SDK RPC contract exposes status, login, set_enabled({enabled}), set_hostname({hostname}), and logout through the same controls as the UI/CLI. Settings are visible through bb plugin config tailscale. Native credentials live in the OS user config directory under bb-plugin-tailscale/<installation-uuid> with private permissions; the UUID is in plugin KV storage. Preserve both when moving an identity. Do not run two bb instances against the same identity.

Update or move an existing installation

In the installed checkout, run git pull --ff-only, repeat the dependency and helper build commands, then run bb plugin build . and bb plugin reload tailscale. Reload briefly disconnects remote sessions and retains settings and identity.

To move an existing local installation to this checkout, build it and run bb plugin install "$PWD". BB replaces the local source for the same tailscale plugin ID while retaining its settings and storage. Install the new path directly instead of uninstalling first. The original generated name remains the default until you choose another name.

Security and troubleshooting

Only untagged peers whose stable Tailscale user ID matches this embedded node’s owner are admitted. The helper rejects identity lookup failures, foreign Origin/Host values and explicit cross-site requests. It forwards HTTP, uploads, streams and WebSockets only to bb’s fixed loopback URL, and strips supplied forwarding/identity assertions. Existing remote connections close when owner identity is lost. Tailnet ACLs remain an additional restriction.

No Funnel, arbitrary port forwarding, subnet routing, system Tailscale configuration or cloud enrollment is involved. Enabling access grants your authorized devices the full bb interface, including files and terminals.

If the helper is missing, run the build command and reload with bb plugin reload tailscale. Unsupported platforms fail explicitly. For HTTPS/MagicDNS errors, enable them in your personal tailnet and retry. For approval-pending, approve the new node in that tailnet’s admin console. A bound socket alone is insufficient for ready status: the helper provisions a valid HTTPS certificate first. Authentication links stay in memory and explicit status replies; they are never written to plugin logs or realtime broadcasts.

If sign-in remains pending without a link, check whether your outbound firewall is waiting for approval of bb-tailscale. The helper needs to contact Tailscale's control service before it can produce a sign-in link.

An explicitly configured BB app URL still takes precedence for BB-generated links. This plugin preserves that setting. Use the plugin's HTTPS address for the phone's direct server profile; browser and phone connections use the address you opened or entered.

Verification

nix shell nixpkgs#bun -c bun run typecheck
nix shell nixpkgs#bun -c bun test
nix shell nixpkgs#go -c go -C helper test -race ./...
bb plugin build .

In a fully installed BB monorepo workspace, use nix shell nixpkgs#bun -c bunx turbo run typecheck test --filter=bb-plugin-tailscale to run the JavaScript checks through workspace orchestration. The standalone commands use this plugin’s installed public SDK and local dependencies.

Tests exercise actual fixture subprocesses, bounded IPC, cancellation and process termination, plus the real Go HTTP/reverse-proxy and upgrade paths against a narrow identity fixture. Live installation, Settings interaction, enrollment, phone access and another-user refusal require separate runtime acceptance evidence. Deterministic tests do not establish phone reachability.

License

MIT. The included license preserves the BB project's copyright notice for the scaffold and UI components used here.