Skip to main content
A Sidecar on the free plan logs in to join your organization: see Connect with approval (no token). An Enterprise Sidecar connects with a token instead: on boot it asks the Control Plane what its configuration should be, and from then on the Control Plane owns that configuration.
Deploying many Sidecars with automation? Skip the per-Sidecar token: Service Accounts lets each one authenticate with its Kubernetes or Google service account, and the Control Plane creates it on the first handshake.

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

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.
Connect a Sidecar page with a pending request, the code, the Sidecar name field, and the Approve and Deny buttons
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.
Connect a Sidecar page after approval, with the message that the Sidecar is approved
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.
Sidecar details page with the Active status and a recent check-in
The Sidecar saves its token 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.
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.
Write a values.yaml:
values.yaml
  • config is the Sidecar’s config file. The Control Plane copies it once, on the first start. It needs at least one entry in listeners.
  • This file holds the token. Keep it out of a repository.
Install the chart:
A Sidecar that already runs from the chart: add the controlPlane block to its values and run the same helm upgrade. The chart restarts the pods. See Kubernetes for every value.
On the first start the Control Plane holds no configuration for this Sidecar. It answers 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 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.
On Kubernetes, run 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:
While that header is present, the Sidecar’s own license sources — the --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 as control 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.
A Sidecar newer than its Control Plane runs, but cannot use a setting the Control Plane does not know. Its first import fails when its config file uses such a setting, and the Sidecar does not start. Do not roll the Control Plane back below a setting a stored configuration uses: the Control Plane then answers 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:
The Control Plane then sends only that flag and the license, and the Sidecar runs the config file it was started with. The switch deletes the Control Plane rules imported from this Sidecar that nothing else uses, and unbinds the rest. Send {"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.