Connect a Sidecar

Issue a token, point a Sidecar at the Control Plane, and let it pull its configuration.

A Sidecar that knows nothing about a Control Plane reads its config file from disk and runs. Connecting it changes one thing: on boot, it asks the Control Plane what its configuration should be.

---

The handshake

Four properties fall out of this shape, and they are the reason it looks like this:

• No session to maintain. The Sidecar loads its configuration into memory and keeps running. A Control Plane that goes down does not take running Sidecars with it.
• The token is the authentication. There is no second credential and no certificate exchange.
• Ordinary HTTP. A plain request and a plain response. Nothing is tunnelled and nothing bidirectional stays open.
• Neither side knows the other’s physical address. The Sidecar dials out; the Control Plane never dials in. No inbound firewall rule, no NAT traversal.

---

Steps

1. Issue a token in the Control Plane

   Create a Sidecar registration and copy the token it returns. The token identifies this Sidecar and authenticates it — treat it as a credential.

2. Point the Sidecar at the Control Plane

   Add the Control Plane’s URL to the Sidecar’s config file. The token is never written to disk — it goes on the command line or in an environment variable:

   config.yaml

   control_plane_url: https://hoop.your-company.com
   

   hoop start sidecar --config config.yaml --token "<the token you copied>"
   

   Or supply both through the environment, which is the shape a Kubernetes deployment wants — mount the secret, set the variables, pass no arguments:

   export HOOP_CONTROL_PLANE_URL=https://hoop.your-company.com
   export HOOP_SIDECAR_TOKEN=<the token you copied>
   
3. Start it

   hoop start sidecar --config config.yaml --token "<the token you copied>"
   

   The first handshake uploads this whole file. Everything the Control Plane manages — listeners, guardrails, masking, analyzer settings — arrives over the ping.

4. Confirm what it resolved

   The admin API reports the merged, live configuration. This is the only place you can see what the Sidecar actually ended up running:

   curl -s localhost:19000/healthz            # ok
   curl -s localhost:19000/config | python3 -m json.tool
   

   The Sidecar should also appear in the Control Plane’s list, with a recent check-in.

---

Troubleshooting

Symptom	Check
The Sidecar starts but never appears in the Control Plane	Outbound HTTPS to the Control Plane host. The Sidecar dials out; nothing dials in.
It appears, but runs no managed guardrails	Read /config on the admin API. A Sidecar that could not fetch falls back to its local file.
Authentication fails	The token is per-Sidecar. Reusing one across two Sidecars is not a supported shape.
Rules changed centrally but the Sidecar did not	Configuration is picked up on the ping, not pushed. Wait for the next interval or restart the Sidecar.
My listeners never reached the Control Plane	It already had a configuration for this Sidecar, so it kept that one. Edit the listeners there.

---

Next

Control Plane

What it manages and why the protocol is this simple.

Install the Control Plane

Docker Compose, Kubernetes and AWS.

Config File Reference

Every source for control_plane_url and the token, in precedence order.