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. A level that holds statements for a person is the exception: its listener files each held statement with the Control Plane, and denies that statement while the Control Plane is unreachable.
- The token is the authentication. There is no second credential and no certificate exchange. A Sidecar can use a service account instead of a token, never both.
- 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.
Choose a method
Both methods end with the same handshake. With approval, the Sidecar gets its token without a copy and paste.
The free plan uses the hosted Control Plane,
https://use.hoop.dev. Your own Control Plane needs Enterprise. On your own Control Plane, the two methods are available, and its web app approves the request.
Connect with approval (no token)
Start the Sidecar with the Control Plane URL only. The Sidecar sends a connection request. An admin approves the request in the web app. Then the Sidecar connects. You do not copy a token. The Sidecar makes its own token and sends it one time with the request. The Control Plane keeps only a hash of the token.Free tier: one Sidecar per organization, with one Guardrail, one Data Masking rule and one Access Request rule. The Sidecar logs in to join your organization. More than one rule per feature, more than one Sidecar, or your own Control Plane needs Enterprise.
1
Set the Control Plane URL
On the free plan, skip this step. Without a URL, the Sidecar sends the request to
https://use.hoop.dev.For your own Control Plane (Enterprise), set HOOP_CONTROL_PLANE_URL to its address. Do not set HOOP_SIDECAR_TOKEN.http://localhost:8009 is the address of a Control Plane that runs on your machine. The Sidecar reads the address from HOOP_CONTROL_PLANE_URL, then from control_plane_url in the config file.2
Start the Sidecar
- CLI
- Docker
Install the CLI from Command Line. Then start the Sidecar:The terminal shows a URL and a code:The Sidecar waits for the approval. The code stops working after 10 minutes. Start the Sidecar again to get a new code.
3
Open the request in the web app
Sign in to the web app as an admin. Open the URL from step 2.If your browser cannot open the URL, open 
/sidecars/login on your Control Plane. Type the code in the Code field. Click Continue.The Connect a Sidecar page shows the pending request and its code.
4
Approve the request
Make sure that the code on the page is the same as the code from the Sidecar. If the codes are different, click Deny.Change the Sidecar name if necessary. Click Approve.The page shows that the Sidecar is approved. The Sidecar is now in your organization.

5
Make sure that the Sidecar is connected
The Sidecar connects by itself after the approval. A Sidecar that you started in a terminal without a config file first shows a setup screen. Complete the setup in the terminal.In the web app, click Sidecars in the menu. Open the Sidecar. Before the setup is complete, the status is Waiting. After the setup, the status is Active and the page shows a recent check-in.

~/.hoop/sidecar/credentials.json, or in the folder that HOOP_SIDECAR_STATE_DIR names. The next start uses the saved token and does not ask for approval.
Connect with a token
Two ways to connect
Both paths end the same way — a token, pointed at the Control Plane — and both use the steps below.- Connect an existing Sidecar — it already runs in your infrastructure. Issue a token, set the Control Plane URL and token, and restart it with the token.
- Create and deploy a new Sidecar — you have not deployed one yet. Issue a token, then deploy with Kubernetes, Docker or the CLI using the tabs in step 2 below; each tab links to its full install page.
Steps
1
Issue a token in the Control Plane
Create a Sidecar registration and copy the token it returns. It is shown once and stored only as a hash, so losing it means registering a new Sidecar.The token identifies this Sidecar and authenticates it — treat it as a credential.
2
Choose where it runs, and start it
The Control Plane’s URL goes in the config file or an environment variable. The token is never written to disk — it goes on the command line or in an environment variable. Pick where the Sidecar runs. A Sidecar that already runs keeps its image and config file: it only needs the URL, the token and a restart.On the first start the Control Plane holds no configuration for this Sidecar. It answers
- Kubernetes
- Docker
- CLI / Bare metal
Two ways to deploy on Kubernetes. The Helm chart does most of the work for you. Your own YAML gives you full control, and you write each object yourself.New to Kubernetes? Use the Helm chart.
- Helm chart
- Your own YAML
Write a A Sidecar that already runs from the chart: add the
values.yaml:values.yaml
configis the Sidecar’s config file. The Control Plane copies it once, on the first start. It needs at least one entry inlisteners.- This file holds the token. Keep it out of a repository.
controlPlane block to its values and run the same helm upgrade. The chart restarts the pods. See Kubernetes for every value.412, the Sidecar imports the document from your local file, and then serves what the Control Plane sends back. That import happens once.3
Edit the configuration in the Control Plane from now on
The Control Plane owns the whole document after the import — listeners included. The two are never merged. Listeners left in the local file are ignored, and the Sidecar says so at startup:
--config becomes optional at this point. The URL and the token are enough to start.4
Confirm what it resolved
The admin API reports the live configuration. It runs only when the configuration names an address for it — there is no default port. The On Kubernetes, run
config.yaml from step 2 sets it with this block:listen serves the probes. api_listen serves /config and the other read routes, and is off unless set. To add or change either later, edit the Sidecar’s configuration in the Control Plane, then restart the Sidecar.kubectl port-forward deploy/<your-sidecar-deployment> 19002:19002 first. The chart does not publish 19002.The Sidecar should also appear in the Control Plane’s list, with a recent check-in.The license
The organization’s license lives on the Control Plane, not on each Sidecar. It rides on the handshake response, and the response carries a header saying the Control Plane owns the decision:--license flag, HOOP_LICENSE and the config file’s license key — are ignored, and it warns at startup that it is ignoring them. A Control Plane whose organization holds no license runs the free tier.
A license key authored on a Sidecar’s configuration in the Control Plane is refused. One organization, one license.
A license change in the Control Plane reaches each Sidecar on its next heartbeat, with no restart.
Connecting a licensed standalone Sidecar takes a restart, and after it the Control Plane’s license is the only one. Set the organization’s license first: rules past the free tier do not start without a current license that covers them. A running Sidecar whose config file starts naming a Control Plane warns about this before the restart.
Staying in sync
A heartbeat repeats the handshake every minute. A change that only touches rules — guardrails, masking, PII, OPA, a listener’s analyzer block — is applied in place and logged ascontrol plane configuration applied. Connections already open drain under the rules they were accepted with.
A change beyond the rules — listeners, audit, admin, log level — logs restart to apply it instead.
A failed heartbeat changes nothing. The Sidecar keeps serving the configuration and the license it last received.
Approval requests do not ride on the heartbeat. A level that holds statements for a person (require_approval) calls the Control Plane once per held statement, and denies the statement when that call fails. A level the approval agent decides calls nothing.
Upgrading
Upgrade the Control Plane first, then the Sidecars. A Sidecar refuses the whole configuration when one key in it is unknown to its version. From 1.210.0 the Control Plane knows what each Sidecar can read:- It sends only the settings an admin set. Upgrading the Control Plane alone changes nothing an older Sidecar receives.
- A save that uses a setting, a rule type or a protocol that a connected Sidecar’s version lacks is refused with
422. The error names the Sidecar and the upgrade it needs. A Sidecar that never connected is checked at its first handshake instead. - This covers every Sidecar from 1.162.0.
500 to that Sidecar.
When a Sidecar refuses a configuration anyway:
The Sidecar page in the Control Plane shows the state, the Sidecar’s version and the reason until a configuration applies.
Not applied for longer than a few minutes means the Sidecar is restarting in a loop.
Escape hatch. An admin can hand the Sidecar back to its own config file:
{"configuration": {"load_from_disk": false}} alone to hand it back: the stored configuration is cleared, and the Sidecar imports its config file again.
Troubleshooting
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 credential, in precedence order.Service Accounts
No token per Sidecar: one entry per cluster, Sidecars created on first contact.