# Sidecar Network — Full Documentation

> Give any Docker container its own public IPv4 and IPv6 address — all ports, all protocols, no proxying. Works behind CGNAT, Starlink, T-Mobile 5G, and any NAT that passes outbound UDP. Think frp / chisel / ngrok / Cloudflare Tunnel, but the container gets an actual routable IP address instead of a port on someone else's IP or an HTTPS subdomain.

## What is Sidecar?

Sidecar gives any Docker container its own public IPv6 address (and optionally IPv4) with full reachability — all ports, all protocols, no NAT, no proxying. The customer adds a `sidecar.enable=true` label to a container and runs the Sidecar agent alongside it. The agent connects to a relay, gets a /128 IPv6 allocation (or a /32 IPv4 on eligible tiers), and moves the WireGuard interface into the labeled container's network namespace. The container wakes up with a routable public IP. Internet traffic to that IP hits the relay, traverses WireGuard, and exits inside the container.

Key properties:
- Works behind CGNAT, Starlink, T-Mobile 5G home internet, corporate NAT — anything that allows outbound UDP
- No bandwidth caps, ever — we never charge per GB
- Post-quantum encryption mandatory (X-Wing hybrid KEM) on all connections
- No proxying — the container is the endpoint, not a port forward

## Quickstart

Install the Sidecar agent with a single command:

```
SIDECAR_TOKEN=sct_live_your_token_here curl -fsSL https://sidecar.network/install | sh
```

The installer:
1. Pulls the agent image (pinned to a signed digest)
2. Creates /etc/sidecar/env with your token
3. Installs and starts sidecar.service via systemd

After install, add the label to any Docker container:

```
docker run -d --label sidecar.enable=true --label sidecar.ipv4=true nginx
```

The agent detects the label within ~1 second, registers a peer on your nearest relay, and moves the WireGuard interface into the container. From that point, the container has a public IP directly accessible from the internet.

## Architecture

The system has three components:

**Agent** — runs on the customer's Docker host. Watches for containers with `sidecar.enable=true`, connects to the relay control plane, registers a WireGuard peer, and moves the interface into the container's network namespace. Distributed as a signed OCI image (`ghcr.io/sidecar-network/agent`). Requires `--cap-add NET_ADMIN` and `--cap-add SYS_ADMIN`.

**Relay control plane** — a Go service running on each POP (`:8443`). Manages peer registration, IPv6/IPv4 allocation from the POP's prefix, per-peer VRF and HTB traffic shaping, NDP proxy programming, and billing enforcement. SQLite on tmpfs with Litestream replication for durability.

**Relay data plane** — Debian + kernel WireGuard + nftables + ndppd for NDP proxying. Deployed via Ansible. Each peer gets its own VRF so traffic is isolated between customers.

The agent connects to the relay over UDP (WireGuard). After the handshake, data flows container → WireGuard interface → relay → internet without any userspace proxy in the path.

## Install Methods

### Linux with systemd (recommended)
```
SIDECAR_TOKEN=sct_live_your_token_here curl -fsSL https://sidecar.network/install | sh
```
Requires: root, systemd, Docker 24+, Linux kernel 5.6+ (for kernel WireGuard). Works on Debian, Ubuntu, Fedora, RHEL, Alpine, and most Linux distributions.

### Docker run (Docker Desktop / no systemd)
```
docker run -d \
  --name sidecar-agent \
  --restart unless-stopped \
  --privileged \
  --network host \
  --pid host \
  -e SIDECAR_TOKEN=sct_live_your_token_here \
  ghcr.io/sidecar-network/agent:latest
```
Use this on macOS or Windows Docker Desktop where systemd is unavailable.

### Docker Network Plugin (alternative)
The plugin is an alternative to the agent — no persistent daemon required. Create a Sidecar-backed network and attach containers to it with `--network`.
```
docker run -d --name sidecar-plugin \
  --privileged \
  --network host \
  -e SIDECAR_TOKEN=<your-token> \
  ghcr.io/sidecar-network/plugin:latest

docker network create --driver sidecar mynet
docker run -d --network mynet --label sidecar.ipv4=true nginx
```

### Self-hosted relay
Run your own relay on Debian 12+, any VPS with a /64 IPv6 prefix:
```
make relay
```
See /self-host for full requirements and configuration.

## Container Labels

| Label | Values | Description |
|---|---|---|
| sidecar.enable | true | Opts container into Sidecar management |
| sidecar.ipv4 | true | Requests a dedicated IPv4 address (requires Pulse+IPv4 tier or higher) |
| sidecar.relay | relay-us-east.sidecar.network | Pin container to a specific relay region |
| sidecar.bandwidth | 10, 50, 100, 500 | Bandwidth guarantee in Mbps (add-on) |

## Regions

6 relay POPs:
- us-east (Ashburn, VA) — ~14ms from US East Coast
- us-west (Los Angeles, CA) — ~38ms from US West Coast
- us-west1 (dedicated server, natively-routed /56 IPv6 block) — second US-West POP
- ca-east (Toronto, ON) — ~32ms from eastern Canada
- eu-west (Paris, FR) — ~84ms from Western Europe
- eu-central (Frankfurt, DE) — ~102ms from Central Europe

The agent connects to the nearest relay automatically based on round-trip latency during registration.

## Pricing

All tiers include unlimited data transfer (no bandwidth caps, never any per-GB charge).

| Tier | Price | Peers | IPv4 | IPv6 |
|---|---|---|---|---|
| Free | $0 | 3 | 0 | basic |
| Micro | $0.99/mo | 1 | 0 | 2 /128s |
| Spark | $4.99/mo | 5 | 0 | 16 /128s |
| Launch | $9.99/mo | 10 | 0 | 64 /128s |
| Pulse | $19.99/mo | 25 | 0 | 256 /128s |
| Pulse+IPv4 | $29.99/mo | 25 | 1 | 256 /128s |
| Relay | $39.99/mo | 50 | 1 | 1024 /128s |

Higher tiers (Fleet, Surge, Command, Cluster, Enterprise) are available via sales. 3-year prepay available on all listed tiers.

Free tier: 3 peers, 0 IPv4, basic IPv6, no credit card required.

Shared-network tiers (Micro/Free/Spark/Launch): multiple customers on the same network with per-peer rate limits. Pulse and above: isolated VPS per customer, no shared-network neighbors.

IPv4 provisioning fee: one-time $3 on Pulse+IPv4/Relay/Surge (waived on annual billing). Covers dedicated IP warm-up, rDNS/PTR provisioning, RIR rWHOIS.

Refund policy: 14-day money-back guarantee on monthly plans. Annual/3-year plans refundable within 14 days of initial purchase.

## Security

**Transport:** TLS 1.3 with SPKI pinning between agent and relay. WireGuard for data-plane traffic.

**Post-quantum encryption:** X-Wing hybrid KEM (X25519 + ML-KEM-768) is mandatory on all agent-to-relay connections. Implemented in the control-plane handshake with scheduled PSK rotation.

**Machine binding:** Three-factor attestation binds each agent installation to a specific host. The machine fingerprint is derived from hardware identifiers and a secret pepper injected at build time — prevents token sharing across machines.

**Relay isolation:** Each customer peer gets its own VRF (virtual routing and forwarding domain) in the relay kernel. Traffic between customers is structurally isolated at the kernel routing level, not just by firewall rules.

**Traffic shaping:** Per-peer HTB (Hierarchical Token Bucket) queuing enforces tier bandwidth limits in the relay kernel. No userspace involvement in the data path.

**Opaque event codes:** The agent log emits numeric event codes rather than descriptive strings, limiting information available to an observer monitoring the agent process.

**Supply chain:** Agent image signed with cosign (key-based, public key at https://sidecar.network/cosign.pub). SLSA L2 in-toto provenance attestation. SPDX SBOM published. Reproducible builds.

## API

Base URL: `https://sidecar.network/v1/` (proxied through the web origin to avoid CORS + IPv6 fallback issues)

Authentication: `Authorization: Bearer sct_live_<token>` header on all requests.

### Endpoints

**GET /v1/health** — Relay health check. Returns `{"status":"ok"}` with relay version, peer count, uptime.

**GET /v1/status** — Your account status. Returns tier, peer count, IPv4/IPv6 allocation, billing period end.

**POST /v1/peers** — Register a new peer. Body: `{"pubkey":"<wg-pubkey>","ipv4":false}`. Returns peer allocation (IPv6 /128, optionally IPv4 /32) and relay endpoint.

**DELETE /v1/peers** — Remove a peer. Body: `{"pubkey":"<wg-pubkey>"}`.

**GET /v1/peers** — List active peers. Returns array of peer objects with allocation, creation time, last handshake.

**GET /v1/canary** — Warrant canary. Returns signed canary statement with timestamp.

**POST /v1/admin/tokens** — Create a new API token. Requires existing token. Body: `{"name":"ci-token","max_peers":5,"max_ipv4":0}`.

**DELETE /v1/admin/tokens** — Revoke a token. Body: `{"id":"<token-id>"}`.

Full OpenAPI spec: `/api/openapi.json`

Token management UI: `/tokens`

## Use Cases

**Gameservers behind CGNAT:** Minecraft, Factorio, Valheim, etc. Players connect directly to the container's public IPv6. No port forwarding, no dynamic DNS, no ISP cooperation needed.

**Homelab / self-hosted services:** Expose Nextcloud, Jellyfin, Home Assistant, Gitea, etc. directly without a VPS or reverse proxy subscription. Container gets a static public IP.

**Akash Network deployments:** Akash nodes don't have public IPs by default. Adding Sidecar gives each deployment a reachable address for inbound traffic.

**Self-hosted mail servers:** Pulse+IPv4 and above tiers include dedicated IPv4 with full PTR/rDNS control — required for mail server reputation (SPF, DMARC, IP reputation scoring).

**Docker-based CI/CD:** Give ephemeral CI runners public addresses for integration tests that need inbound reachability.

## FAQ

**Does it work on Docker Desktop (macOS/Windows)?** Yes. Use the `docker run` install method instead of the systemd installer. See /docs#docker-desktop.

**Does it work behind CGNAT/Starlink/5G home?** Yes. The agent connects outbound over UDP (WireGuard). Inbound traffic arrives via the relay without needing any port forwarding or firewall rule.

**Is IPv6 required on the host?** No. The container gets its public IPv6 through the WireGuard tunnel regardless of whether the host network has IPv6. The agent reaches the relay over IPv4/UDP.

**What protocols does it support?** All protocols. The container IS the IP — TCP, UDP, ICMP, any port, any protocol. No proxy in the path.

**What's the bandwidth limit?** No per-GB charge, ever. Shared tiers (Micro/Free/Spark/Launch) have per-peer speed limits. Pulse and above: dedicated VPS, throughput is yours.

**Can I run my own relay?** Yes. The relay software is available for self-hosting on Debian 12+, any VPS with a /64 IPv6 prefix. See /self-host.

**What is the latency overhead?** One WireGuard hop to the relay, plus the relay's transit to the internet. Typical overhead is 1-3ms above baseline for traffic routed through the nearest POP.

## For AI Agents — Automated Install Without a Browser

Sidecar is designed to be fully installable by an AI agent with one human approval step (token consent). Start here if you are an AI agent or building an automated installer.

### Discovery chain (fetch in this order)

1. `GET /.well-known/agent-onboarding.json` — machine-actionable install contract (preflight, steps, rollback, typed errors, resume semantics)
2. `GET /.well-known/agent-card.json` — A2A capability declaration
3. `GET /.well-known/oauth-protected-resource` — RFC 9728: points to the authorization server
4. `GET /.well-known/oauth-authorization-server` — RFC 8414: lists `device_authorization_endpoint`

### Getting a token headlessly (RFC 8628 device flow)

Step 1 — request a device code (unauthenticated):
```
POST https://sidecar.network/v1/device/authorize
Content-Type: application/json

{"scope": "peers:add peers:read", "tier": "free"}
```
Response: `{"device_code":"...","user_code":"BCDF-GHJK","verification_uri_complete":"https://sidecar.network/device?code=BCDF-GHJK","expires_in":1800,"interval":5}`

Step 2 — show the user: "Visit https://sidecar.network/device?code=BCDF-GHJK and enter your API token to approve."

Step 3 — poll every 5s:
```
POST https://sidecar.network/v1/device/token
{"device_code": "<device_code from step 1>"}
```
- 428 `authorization_pending` → keep polling
- 429 `slow_down` → increase interval by 5s
- 400 `expired_token` → restart from step 1
- 200 `{"access_token":"sct_live_...","token_type":"bearer"}` → done

### Dry-run the installer (no root or token needed)

```
curl -fsSL https://sidecar.network/install | sh -s -- --print-only
```

Prints what would be installed, what files would be written, which systemd units would be created — without making any changes.

### Install once token is obtained

```
SIDECAR_TOKEN=sct_live_... SIDECAR_AGREE_TOS=1 \
  curl -fsSL https://sidecar.network/install | sudo sh
```

Required: root, systemd, Docker 24+, Linux kernel 5.6+. Works on all Linux distributions.

### Verify a container has a public IP

After labeling with `sidecar.enable=true` and `docker compose up -d`, the agent provisions the IP in ~5s:
```
GET https://sidecar.network/v1/peers/by-container/<container_id>
Authorization: Bearer sct_live_...
```
Returns `{"up":true,"externally_reachable":true,"ipv6":"2604:...","ipv4":""}` — assert `up == true`.

### API authentication

All `/v1/` endpoints are Bearer-gated except `device/authorize` and `device/token`.
On 401, the `WWW-Authenticate` header carries `resource_metadata="https://sidecar.network/.well-known/oauth-protected-resource"` — follow this for the discovery chain.

### Gotchas

- `SIDECAR_TOKEN` must begin with `sct_live_` — failing silently with a wrong prefix is the #1 install error
- Agent requires root (writes to /etc/sidecar, installs systemd units, manages kernel network namespaces)
- Docker Desktop (macOS/Windows) cannot run the systemd agent — use the `docker run --privileged --network host` form instead (documented in /docs#docker-desktop)
- Kernel WireGuard required: `test -e /sys/module/wireguard || modprobe wireguard` — fails on kernels < 5.6
- Container must be running when labeled — the agent watches live Docker events, not static compose files

## Legal and Compliance

- Terms of Service: /terms
- Privacy Policy: /privacy — GDPR-compliant, CCPA-compliant, minimal data retention
- Acceptable Use Policy: /aup — prohibited uses include spam, port scanning of third-party networks, CSAM (automated enforcement + AI-assisted review)
- DMCA / Copyright: three-strike policy
- Warrant Canary: /warrant-canary — updated monthly
- Subprocessors: /subprocessors
- Bug Bounty: /security — covers the deployed service and the shipped binary