Crew Bridge and Relay

Use the crew bridge when your crew spans multiple machines or networks. The bridge runs locally and uses the Recalletta API relay so agents can coordinate without direct host-to-host visibility.

What It Is

The bridge is a background process that:

registers your machine with the relay (hostname + crew name)
polls the relay for inbound messages and delivers them locally
sends outbound messages to the relay or directly to another bridge

When To Use It

Use it for cross-machine crew coordination or when machines cannot reach each other directly. For a single-machine crew, you do not need the bridge.

Quick Start

recalletta login
recalletta crew bridge start
recalletta crew list
recalletta crew message <HOST>:<CREW>:<AGENT> "Message"

Run recalletta login once per machine to store the API key required for relay and discovery.
Use the hostname shown in recalletta crew list (or hostname) for <HOST>. Auto-discovery handles the rest.
Remote messaging uses crew message with a remote target format. See the message command section below.

Commands

Start the bridge

$ recalletta crew bridge start

Starts the bridge server and background relay loops. Uses crew.bridge_port from ~/.recalletta/config.json (default: 8888).

Stop the bridge

$ recalletta crew bridge stop

Stops the bridge process recorded in the crew database.

List machines

$ recalletta crew list

Shows machines registered with the relay. If the bridge is running, it uses the cached peer list; otherwise it fetches from the API (requires an API key).

Send a message to a remote agent

$ recalletta crew message <TARGET> [MESSAGE] [--from <FROM>] [--file <FILE>]

Sends a message to a remote crew agent via the bridge.

The target uses the remote format (e.g., crew:agent or a hostname-qualified target).
--from overrides the sender name.
--file attaches a file to the message (remote targets only; counts toward payload limits).

Examples

$ recalletta crew bridge start
$ recalletta crew list

$ recalletta crew message summit-lab:Atlas:beacon "Review ready"
$ recalletta crew message summit-lab:Atlas:beacon "Report attached" --from forge --file ./report.md

How It Works

The bridge starts an HTTP listener on crew.bridge_port (default 8888).
It sends a heartbeat to the relay every 60s (immediate on startup) with your hostname and crew name.
It polls the relay for inbound messages and ACKs them after delivery.
Peer discovery runs about every 15s with backoff on failures.
A peer is considered offline after 5 minutes without a heartbeat; the bridge prints [bridge] <host> (<crew>) is now online and [bridge] <host> (<crew>) went offline (last seen ...) notifications.

Manual Override: relay_hosts

If auto-discovery cannot see a host, add it to crew.relay_hosts in ~/.recalletta/config.json to force relay routing:

{
  "crew": {
    "relay_hosts": ["summit-lab", "buildbox.local"]
  }
}

crew message with a remote target will also do a one-shot relay peer lookup even if the bridge is not running. If the hostname shows as online, it routes via the relay without needing relay_hosts.

Limits (Relay)

256 KB max payload per message (message + attachments)
500 messages per hour
20 peers per account
50 MB queued payload storage
72 hour message TTL (expired if not acknowledged)

Hostname Requirement

Relay routing and discovery use the OS hostname string. Use the hostname listed in recalletta crew list (or hostname). IP addresses do not match the relay peer list.

Troubleshooting

Hostname mismatch: use the exact hostname from recalletta crew list, not an IP or alias.
No API key: recalletta login to store ~/.recalletta/config.json credentials.
Bridge not started: run recalletta crew bridge start on both machines.
Messages not arriving: confirm the target appears online in recalletta crew list, then check payload size or rate limits and that the target uses the remote crew:agent format.