Host a telemetry receiver

kusaw-control-plane is a small service you host to receive telemetry from your factories. It checks each batch, stores it in a SQLite file, and deletes records after the retention window. It sends nothing anywhere and needs no outside service.

It accepts the factory-telemetry/1 batches described in Telemetry. It stores each record exactly as received, plus when it arrived and which sender sent it.

Build itCopy Anchor Link

From the Kusaw source:

go build -o kusaw-control-plane ./cmd/kusaw-control-plane

Configure itCopy Anchor Link

Write a config file, for example control-plane.yaml. Tokens and signing keys are never in the file; it names the environment variables that hold them.

listen: 127.0.0.1:8472
storage: data/control-plane.db
retention_days: 180
viewer_token_env: CP_VIEWER_TOKEN
senders:
  - label: platform-team
    token_env: CP_PLATFORM_TOKEN
    signing_key_env: CP_PLATFORM_SIGNING_KEY

• listen — the address to serve on. Default 127.0.0.1:8472.
• storage — the SQLite file. Relative paths are relative to the config file. Postgres is not supported yet.
• retention_days — how long records are kept. Default 180. Older records are deleted at start and then once a day.
• tls_cert and tls_key — set both to serve HTTPS yourself, or leave both out and put the service behind your HTTPS proxy.
• viewer_token_env — the variable with the token for the read API.
• senders — one entry per factory or team that reports. Each has a label (stored with its records), the variable with its bearer token, and the variable with its signing key.

Check the file without starting the service:

kusaw-control-plane --config control-plane.yaml --check

Then start it:

kusaw-control-plane --config control-plane.yaml

Point a factory at itCopy Anchor Link

In the factory's kusaw.yaml, set the endpoint to the receiver's /ingest URL:

telemetry:
  endpoint: https://telemetry.example.com/ingest
  token_env: KUSAW_TELEMETRY_TOKEN
  signing_key_env: KUSAW_TELEMETRY_SIGNING_KEY

Give the factory the same token and signing key as its sender entry, in those environment variables, then run kusaw telemetry on.

What the receiver refusesCopy Anchor Link

• unauthorized (401) — no bearer token, or one that matches no sender.
• signature check failed (401) — the signature doesn't match the body, or the timestamp is more than 5 minutes off.
• batch does not match factory-telemetry/1: <first problem> (400) — the batch fails the schema. Nothing from it is stored.

A batch sent twice with the same Idempotency-Key is accepted and stored once.

Read APICopy Anchor Link

The read API needs the viewer token as Authorization: Bearer <token>.

• GET /api/factories — each reporting factory with its label, sender, run count and last run.
• GET /api/metrics?factory=<factory id>&from=2026-11-01&to=2026-11-14 — totals for runs that finished on those days (UTC, both included): runs, outcomes, cost, runs without a cost, human interactions, median duration, final outcome labels and benchmark runs.
• GET /healthz — ok when the service is up. It needs no token.