Automated setup

Instead of writing sidecar.yaml by hand, the app can generate a config bundle for you: a pre-filled config plus a fresh registration token, packaged so you can mount it straight into a container.

Manual vs automated

	Manual	Automated bundle (this page)
Best for	Infra-as-code shops templating sidecar.yaml themselves (Terraform, Helm values, Ansible)	Getting a first host registered fast; teams without config templating
Token handling	You place the token into your secret store yourself	Token arrives inside the bundle — move it into your secret store
Config drift	You own the file	Regenerate on changes, or edit the YAML — it’s the same format

Either path converges on the same sidecar and the same configuration surface.

Download the bundle

1. In the app, go to Settings → Hosts and click Register host.

2. Choose the label(s) for the host(s) you’re registering (e.g. env=production, service=acme-web) — the generated config includes them, and they feed scan scoping.

3. Click Download config bundle. You get ringzero-sidecar-config.tar.gz:

   • Directoryringzero-sidecar-config/

     • sidecar.yaml pre-filled: api_url, labels, token file path
     • token a freshly issued registration token (rz_reg_…)

The bundled sidecar.yaml is exactly the documented format, with registration_token_file pointing at /etc/ringzero/token — the bundle is designed to be mounted as one directory at /etc/ringzero. Nothing is magic; you can edit it.

The bundle contains a live secret

The token file is a real registration token, issued at download time with your org’s default lifetime. Treat the whole bundle as a secret: don’t commit it, don’t share it over chat, and store it in your secret manager if you keep it at all. Each bundle’s token is listed in Settings → Hosts → Registration tokens with a “bundle” badge, its id (e.g. tok_4a1f), and its download timestamp — revoke it there any time.

Use the bundle

Docker Compose

Extract next to your compose.yaml (outside the build context) and mount the whole directory at /etc/ringzero:

tar -xzf ringzero-sidecar-config.tar.gz

compose.yaml

services:
  app:
    image: acme/acme-web:latest

  ringzero-sidecar:
    image: ghcr.io/ringzero/sidecar:1
    restart: unless-stopped
    ports:
      - "7301:7301"
    volumes:
      - ./ringzero-sidecar-config:/etc/ringzero:ro

Kubernetes

Load the bundle into a Secret, then mount it at /etc/ringzero:

tar -xzf ringzero-sidecar-config.tar.gz
kubectl create secret generic ringzero-sidecar \
  --from-file=sidecar.yaml=ringzero-sidecar-config/sidecar.yaml \
  --from-file=token=ringzero-sidecar-config/token

pod spec fragment — full manifests in the deployment guides

containers:
  - name: ringzero-sidecar
    image: ghcr.io/ringzero/sidecar:1
    ports:
      - containerPort: 7301
    volumeMounts:
      - name: ringzero-config
        mountPath: /etc/ringzero
        readOnly: true
volumes:
  - name: ringzero-config
    secret:
      secretName: ringzero-sidecar

Running more than one replica of the workload? Read the Kubernetes reachability patterns first — a shared Service can’t route the challenge correctly.

Then verify registration the same way as in the manual setup (step 5): logs show host registered, and Settings → Hosts shows the host active.

Bundle expiry and regeneration

• The bundled token expires like any registration token (org default, shown at download time). After expiry the bundle can’t register new hosts; hosts already registered keep working.
• Regenerate any time with Register host → Download config bundle — each download issues a distinct token, so you can hand different bundles to different teams/pipelines and revoke them independently.
• One bundle can register many hosts (e.g. baked into a deploy pipeline for a fleet) — each host gets its own hst_… registration.

Rolling out to a fleet

At fleet scale, treat the bundle as the source of your templated config rather than mounting it verbatim:

• Template sidecar.yaml in your Helm values / Terraform / Ansible from the bundled one; keep the token in your secret manager and project it via registration_token_file.
• One token per pipeline or team — revocation stays granular, and the audit trail attributes registrations cleanly.
• Differentiate hosts per environment with RINGZERO_LABELS (it replaces the config file’s labels — set the full map).
• For replicated Kubernetes workloads, deploy the sidecar once per node via the DaemonSet pattern instead of once per pod.
• Ephemeral hosts (CI runners, preview envs): set deregister_on_shutdown: true so they leave scan scope in seconds.