Connect & SSH

Once you're paired, two commands open sessions: connect gives you a local TCP port that pipes to a service behind your gateway, and ssh is the same thing with the system ssh exec'd against that port for you.

burrowee connect

burrowee connect --svc <name> [--local <addr>]

connect starts a local listener, opens a carrier to the relay, completes the per-service end-to-end handshake with the gateway, and pipes every connection to the local port through that encrypted stream. The relay only ever sees sealed bytes.

--svc is the only required flag — it names the target on the gateway side, e.g. "22" for SSH or "8080" for a web service. By default the listener binds 127.0.0.1:0, i.e. an ephemeral loopback port; connect prints what it picked:

listening on 127.0.0.1:54321 → relay wss://relay.example.com/ws gw=1a2b3c4d5e6f7a8b svc=8080

Pass --local to pin the port instead:

burrowee connect --svc 8080 --local 127.0.0.1:8080

Then point any TCP client at it — curl http://127.0.0.1:8080/, a browser, a database client. connect runs until you Ctrl-C it.

burrowee ssh

burrowee ssh --svc 22 [ssh args…]

ssh = connect on an ephemeral loopback port, then exec the system ssh against it. Anything after the Burrowee flags is appended to the underlying ssh invocation, which is always ssh -p <port> localhost [your args…] — so the host is always localhost, and you pick the remote user with ssh's own -l flag rather than user@host:

burrowee ssh --svc 22 -l alice

Your ssh config, keys, and agent all apply as usual; Burrowee only supplies the transport underneath.

Flags and where defaults come from

Both commands share the same flag set:

Flag	Meaning
--svc <name>	service name, e.g. "22" (required)
--local <addr>	local listen address (default 127.0.0.1:0; connect only — ssh always uses an ephemeral port)
--relay <url>	relay WebSocket URL (ws://… or wss://…); default from config
--relay-quic <addr>	relay QUIC address (host:port); default from config, empty disables QUIC
--gw <id>	gateway id; default from config
--gw-pub <file>	gateway ed25519 public key (hex file); default from config
--psk <file>	pairing PSK file; default from config
--config <path>	config.json path (default ~/.burrowee/cli/config.json)

Precedence is simple: an explicit flag always wins, individually; anything you leave off is filled from the bootstrap config (--config just changes where that file is read from). The relay default is the WS URL of your default relay; --relay-quic defaults from config only when the config is consulted. If you pass all four of --relay, --gw, --gw-pub, and --psk, the config file is not read at all — handy for scripted, fully-explicit invocations. With no usable config and missing flags you get a pointer back to burrowee bootstrap.

QUIC and WSS

Each connection's carrier prefers QUIC when the relay advertises a QUIC address (from config or --relay-quic) and falls back to WebSocket over TLS (WSS) when QUIC can't get through — strict firewalls and some corporate networks block UDP. You don't have to choose; the selector races QUIC first and falls back automatically. Set --relay-quic "" to force WSS.

LAN-first dialing

If your default relay has published LAN origins (a relay on the same network as you — see Relays), connect and ssh try those origins first with a short ~2-second budget per hop, verifying the relay's pinned certificate fingerprint, before falling back to the stored internet-facing URL. On your home or office network this keeps traffic local and fast; away from it, the LAN attempts fail quickly and the normal relay path takes over. No flags needed — it's driven entirely by the relay entries in config.json.