Deploy a standalone collector

This is the operator walkthrough for standing up a standalone collector — the dial-out container you deploy near a network the core can’t reach directly. If the core can already reach your devices, you don’t need this: use the built-in embedded collector.

A standalone collector dials out to the core, so the site it lives in needs outbound reachability to the core and nothing inbound — no ports opened toward the collector or the site.

• A host at the site that can run the collector container (Docker), with outbound network access to the Taranac core’s API.
• The core’s (or edge’s) CA certificate, so the collector can verify the core’s TLS.
• The RBAC permission to manage collectors on the core (collectors / ncm_devices edit) to issue the enrollment token.
• Local reachability from that host to the devices you want to collect.

In the core UI, go to Settings → System → Collectors and add a collector. Give it a name and a Site / Location label (free text, for humans — the core never calls the collector, so this is just where you note where it lives). Save; it starts life with status Unknown because it hasn’t reported in yet.

Open the new collector and choose Enroll. Pick a token TTL (default 60 minutes — long enough to deploy, short enough to limit exposure) and confirm. The dialog shows, once:

• the enrollment token (a one-time secret), and
• a ready-to-paste join command, of the form:

./deploy/collector-join.sh \
  --core https://<your-core>/api/v1 \
  --enrollment-token <token> \
  --ca-file /path/to/core-or-edge-ca.crt

On the site host, run the join command from the dialog (pointing --ca-file at the CA cert you staged). On first boot the collector:

1. Generates its own Ed25519 identity key and persists it locally (private key, mode-restricted, never leaves the box).
2. Redeems the one-time token against the core, which pins the collector’s public key as its identity.
3. Deletes the token (it’s spent) and starts long-polling the core for work.

From here every request the collector makes to the core is signed with its Ed25519 key and timestamped — there’s no long-lived shared secret on the wire.

Back on the core, the collector’s status flips to Online once it reports in. Then:

• Set the collector field on the sources for that site (or bulk-onboard the site’s devices with this collector selected).
• Use Collect now on a config to confirm end-to-end reachability, then check the version rail for the first snapshot.

The collector keeps a small amount of durable state on a named volume that must persist across container restarts and image updates:

• its identity (the Ed25519 private key, public cert and fingerprint), and
• its outbox — the local, durable store-and-forward buffer of results not yet acknowledged by the core.

The outbox is what makes a brief link outage or a restart safe: buffered captures are re-delivered idempotently, so nothing is lost and nothing is double-written. If you destroy that volume, the collector loses its identity and must be re-enrolled.

Note the collector stores no device credentials at rest — those are handed to it just-in-time per collection and used only in memory.

• Rotate / re-enroll — revoke the collector’s identity on the core, issue a fresh token, and re-run the join on the host. The new identity overwrites the old one.
• Revoke — from the collector’s detail page, Revoke identity invalidates its key immediately; the next signed request it makes is rejected. Use this if a site host is decommissioned or compromised.

The collector image and the core must agree on the snapshot-identity version (how configs are scrubbed and hashed). If they diverge — e.g. you upgrade the core but not the collector — the core fail-closes that collector: it stops dispatching work and stops ingesting results until the collector is upgraded to match. Upgrade collectors alongside the core.

• Collectors — embedded vs standalone, health and enrollment concepts.
• Tracked configs & transports — pointing sources at your collector.
• Bulk onboarding — onboard a whole site through the new collector.
• Credentials & the vault — the just-in-time credentials handed to the collector.