Skip to content
sidecar(1) · CLI

One binary.
Seven verbs.

Optional control plane CLI for power users. Talks to the same /v1 endpoints the agent uses. macOS and Linux. No daemon required.

Install

NOT YET AVAILABLE — the standalone CLI binary does not exist yet. The agent handles all peer lifecycle automatically via Docker labels. The commands below document the planned interface and cannot be installed or run today.
terminal (planned)
$ brew install sidecar-network/tap/sidecar # or $ curl -fsSL sidecar.network/install | sh

Reads SIDECAR_TOKEN from env or ~/.config/sidecar/config. macOS · Linux · single static binary · no Python, no Node, no daemon.

Usage

sidecar --help
NAME sidecar — manage Sidecar Network peers from the terminal USAGE sidecar <command> [flags] COMMANDS attach <name> attach a container · assigns IPv6 /128 + optional IPv4 if plan supports detach <name> tear down the peer · releases the address back to the pool list list active peers · shows IPs, latency, handshake age, bandwidth inspect <name> full peer detail · key fingerprint, firewall, tx/rx rotate <name> rotate your encryption keys now · forces reconnect within 5s region <new> change relay region · migrates peer and preserves IP if possible (~3 min) doctor end-to-end diagnostics · agent socket · relay reachability · uplink FLAGS --token string API token (default: $SIDECAR_TOKEN) --relay string relay URL override --json output JSON instead of human text --quiet suppress all output except errors -h, --help show help

attach

Attach a running container by name or ID. The agent assigns an IPv6 /128 from your relay's /64. With --ipv4 it also allocates a dedicated IPv4 /32 from the pool (requires a paid plan).

terminal
$ sidecar attach minecraft ✓ peer registered ✓ tunnel created ✓ encryption negotiated ✓ live Container minecraft IPv6 2604:2dc0:101:200::42 IPv4 — (add --ipv4 to allocate) Relay relay-us-east1 · 14ms Key fp: 8a3f…c219

detach

Remove the tunnel peer for a container, release its IPs back to the pool, and delete the network interface from the container's network namespace.

terminal
$ sidecar detach minecraft ✓ peer removed · IPs released · interface deleted

list

List all active peers on your relay. Shows container name, assigned IPs, last handshake age, and transfer counters.

terminal
$ sidecar list NAME IPv6 IPv4 HANDSHAKE RX TX ────────────────────────────────────────────────────────────────────────────────── minecraft 2604:2dc0:101:200::42 15.204.147.97 22s 10.0 MB 2.0 MB valheim 2604:2dc0:101:200::7f — 4m 88.2 MB 12.1 MB

inspect

Show detailed information for a single peer: key fingerprint, firewall rule state, and full traffic counters.

terminal
$ sidecar inspect minecraft minecraft · relay-us-east1 · up 3d 7h IPv6 2604:2dc0:101:200::42/128 IPv4 15.204.147.97/32 WG pubkey abc123...== Key fingerprint 8a3f…c219 Last handshake 22s ago Rx 10.0 MB Tx 2.0 MB Firewall isolation · active

rotate

Rotate the encryption keys for a peer without changing its IP addresses. The peer stays live throughout — no downtime.

terminal
$ sidecar rotate minecraft ✓ encryption keys rotated ✓ tunnel rekeyed new fp: d91e…4a72

region

Move all peers to a different relay region. The CLI tears down the existing peers, provisions new ones in the target region, and updates your DNS records if you have a domain configured. Takes approximately 3 minutes.

terminal
$ sidecar region eu-west ! This will reprovision all peers on relay-eu-west. Continue? [y/N] y ✓ detached from relay-us-east1 (2 peers) ✓ provisioned on relay-eu-west (84ms) ✓ all peers live

doctor

End-to-end diagnostics. Checks agent connectivity, ctrl service status, tunnel liveness, key freshness, and relay reachability. Use this first when something is wrong.

terminal
$ sidecar doctor ✓ agent socket connected ✓ ctrl service relay-us-east1 · TLS OK ✓ relay reachable 14ms · all relays healthy ✓ tunnel liveness minecraft · last handshake 22s ✓ key freshness 8a3f…c219 · rotated 3d ago ✓ firewall rules isolation active All checks passed. ✓

Flags

FlagDefaultDescription
--token $SIDECAR_TOKEN API bearer token
--relay auto Override relay URL
--json false Output JSON instead of human-readable text
--quiet false Suppress all output except errors
--ipv4 false Request a dedicated IPv4 /32 (attach only)

Environment

VariableDescription
SIDECAR_TOKEN Bearer token. Takes precedence over config file.
SIDECAR_RELAY Relay URL override.
SIDECAR_CONFIG Path to config file. Default: ~/.config/sidecar/config
NO_COLOR Disable ANSI colour output when set.

Exit codes

CodeMeaning
0Success
1General error (see stderr)
2Bad arguments or missing flags
3Auth failure — token invalid or expired
4Relay unreachable
5Agent socket not found — is the agent running?