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

Coming soon — the standalone CLI binary is not yet available for download. The agent handles all peer lifecycle automatically via Docker labels. This page documents the planned CLI interface.
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-east · 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-east · 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-east (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-east · TLS OK ✓ relay reachable 14ms · 6 regions · all 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?