Update an executor's API key

An executor authenticates with the exc_ API key stored in its own config. When you rotate or replace that key in the UI, the old key is revoked immediately — but the executor keeps presenting whatever key is still in its config. This recipe shows where the key lives and how to swap it in, for both backends.

If the executor was offline when you rotated its key, it can’t recover on its own: it still holds the old key, which no longer exists, so it fails to authenticate the moment it comes back. Apply the new key with the steps below and it reconnects on the next sync.

Before you start

The new exc_ key — shown only once, when you created or rotated it. If you don’t have it, rotate again to mint a fresh one.
Owner or admin to rotate the key; shell access to the host (Agent) or cluster (Operator) to apply it.

Agent (bare-metal)
Operator (Kubernetes)

The Agent reads its key from [hub] token in /etc/nvcl/agent.toml, once at startup. Update the file and restart the service.

Write the new key

Edit /etc/nvcl/agent.toml as root and replace the [hub] token value:

[hub]
url = "https://hub.novacula.io"
token = "exc_…new-key…"
name = "my-host"

Or in place, without opening an editor:

sudo sed -i 's|^token = .*|token = "exc_…new-key…"|' /etc/nvcl/agent.toml

Keep the file mode 0600 and owned by root — the token is the credential.

Restart the agent

sudo systemctl restart nvcl-agent.service

The config is read once at startup, so the restart is what picks up the new key. Running nodes are unaffected — their nvcl-node-* units keep running.

Confirm it reconnected

journalctl -u nvcl-agent.service -n 100 -f

The Executors row flips back to online within a few seconds. Auth errors here mean the key is wrong or has trailing whitespace.

The Operator reads its key from [hub] token in operator.toml, which Helm renders into the nvcl-operator-config Secret and mounts read-only into the pod. Re-run Helm with the new token — the pod rolls itself.

Upgrade the release with the new token

helm upgrade nvcl-operator oci://ghcr.io/rsquad/nvcl/charts/nvcl-operator \
  --namespace nvcl-system \
  --reuse-values \
  --set-string hub.token="exc_…new-key…" \
  --server-side=false \
  --atomic

This is the command the UI renders on the executor’s Access tab — copy it from there and the token is filled in for you.--reuse-values keeps the rest of your install (Hub URL, name, versions) and changes only the token. --server-side=false forces client-side apply, so the upgrade touches only the credential and doesn’t reassert fields the Operator manages for itself — notably the image its self-update selected. --atomic rolls the release back if the new pod fails to come up, so a bad token can’t leave you with a broken deployment.The chart stamps the pod template with a checksum/config annotation, so changing the token restarts the pod automatically — no separate restart needed.

Confirm it reconnected

kubectl -n nvcl-system rollout status deploy/nvcl-operator
kubectl -n nvcl-system logs deploy/nvcl-operator -f

The Executors row flips back to online within seconds.

If you pinned image.tag at install and the Operator later self-updated, helm upgrade --reuse-values re-applies that pinned tag and can revert the image. To avoid it, pass the current --set image.tag=… (and gateway.tag) as well, or manage the image only through Helm — see the Kubernetes recipe hardening note.

Verify

In Executors, the row returns to online. On the API keys page, the new key’s Last used updates from never to just now, confirming the executor presented it.

API keys — rotate, revoke, and manage the keys themselves.
Provision on bare-metal · Provision on Kubernetes
Connect an executor

​Before you start

​Verify

​Related

Before you start

Verify

Related