Skip to content

discovery.md

Latest commit

 

History

History
78 lines (52 loc) · 3.21 KB

discovery.md

File metadata and controls

78 lines (52 loc) · 3.21 KB
Raw
summary Node discovery and transports (Tailscale, SSH) for finding the gateway
read_when
Adjusting remote connection modes (direct vs SSH)
Designing node discovery + pairing for remote nodes
title Discovery and Transports

Discovery & transports

Bitterbot has two distinct problems that look similar on the surface:

  1. Operator remote control: a client (CLI, Control UI) controlling a gateway running elsewhere.
  2. Node pairing: nodes finding a gateway and pairing securely.

The design goal is to keep all network discovery/advertising in the Node Gateway (bitterbot gateway) and keep clients as consumers.

Terms

  • Gateway: a single long-running gateway process that owns state (sessions, pairing, node registry) and runs channels. Most setups use one per host; isolated multi-gateway setups are possible.
  • Gateway WS (control plane): the WebSocket endpoint on 127.0.0.1:19001 by default; can be bound to LAN/tailnet via gateway.bind.
  • Direct WS transport: a LAN/tailnet-facing Gateway WS endpoint (no SSH).
  • SSH transport (fallback): remote control by forwarding 127.0.0.1:19001 over SSH.
  • Legacy TCP bridge (deprecated/removed): older node transport (see Bridge protocol); no longer advertised for discovery.

Protocol details:

Why we keep both “direct” and SSH

  • Direct WS is the best UX on the same network and within a tailnet:
    • pairing tokens + ACLs owned by the gateway
    • no shell access required; protocol surface can stay tight and auditable
  • SSH remains the universal fallback:
    • works anywhere you have SSH access (even across unrelated networks)
    • requires no new inbound ports besides SSH

Discovery inputs (how clients learn where the gateway is)

1) Tailnet (cross-network)

The recommended “direct” target for cross-network setups is:

  • Tailscale MagicDNS name (preferred) or a stable tailnet IP.

If the gateway can detect it is running under Tailscale, it publishes tailnetDns as an optional hint for clients (including wide-area beacons).

2) Manual / SSH target

When there is no direct route (or direct is disabled), clients can always connect via SSH by forwarding the loopback gateway port.

See Remote access.

Transport selection (client policy)

Recommended client behavior:

  1. If a paired direct endpoint is configured and reachable, use it.
  2. Else, if a tailnet DNS/IP is configured, try direct.
  3. Else, fall back to SSH.

Pairing + auth (direct transport)

The gateway is the source of truth for node/client admission.

  • Pairing requests are created/approved/rejected in the gateway (see Gateway pairing).
  • The gateway enforces:
    • auth (token / keypair)
    • scopes/ACLs (the gateway is not a raw proxy to every method)
    • rate limits

Responsibilities by component

  • Gateway: advertises discovery beacons, owns pairing decisions, and hosts the WS endpoint.
  • Clients (CLI, Control UI): help you pick a gateway, show pairing prompts, and use SSH only as a fallback.
  • Nodes: connect to the paired Gateway WS (manual host/port or tailnet).