Updating the Relay

The relay updates itself — but only to versions you approve. An updater service on the VM asks Calibrant every 5 minutes what version this relay should be running, and installs nothing you have not signed off on. There is no automatic mode and no way to turn approval off.

Why approval exists. The relay runs as SYSTEM on a VM whose identity can read your entire tenant's configuration and — if you enabled the optional Power Platform integration — holds a registration whose admin API also permits writes. Without an approval step, anyone who could publish a build could run code against your tenant within minutes. With it, publishing is not enough — someone in your tenant has to approve a specific version first.

Approving an update

Go to Connections → Calibrant Relay
A pending version appears under Updates on the relay card, with the list of changes it contains
Click the change count to read what is in it
Click Approve on that version — or Approve all next to the heading to go straight to the newest

The relay installs it on its next five-minute update check. The relay service restarts during the install and normally reconnects shortly afterward; scans queued during that window run when it comes back.

Approval names an exact version. It does not roll forward — when a newer version is published, it appears as pending again. That is deliberate: an approval that carried over to future releases would not be an approval of anything in particular.

Approving several at once

When more than one version is waiting, an Approve all button appears alongside the heading. It approves the newest version, which supersedes the ones behind it — the relay installs that version directly rather than stepping through each one. Use the per-version Approve buttons instead if you want to move forward one release at a time.

There is no automatic mode. Every relay installs only what someone in your tenant has approved. That is deliberate: an option to turn approval off would be the single switch that removes the control, and it is the control that stops a published build from reaching your VM on its own.

If you approve nothing, nothing installs — including security fixes. The relay keeps running the version it has, indefinitely. Check the Updates panel when you see a version available, or set a reminder to review it.

What gets verified before anything installs

Every update passes these checks on the VM, in this order:

The complete release manifest must match what your tenant approved. That manifest binds the relay ZIP, updater, PowerShell installer, exact module versions, source commit, and the release notes you reviewed
The downloaded package must match the SHA-256 recorded for that exact version. If it does not, the update aborts before the running relay is touched
If no digest is available, the update is refused rather than installed unverified
Dependencies are installed in a staging directory and the staged JavaScript is checked before the running relay is stopped
The candidate must start, authenticate to Calibrant, and write a fresh health proof before its version is committed. Otherwise the previous installation is restored

Packages are published per version, so approving v1.52 installs v1.52 even after v1.53 ships.

Rolling back

The Updates panel lists older retained releases under Recovery versions once they support the transactional installer. A rollback is another explicit approval; the updater verifies and stages that older release exactly like an upgrade. It keeps the current installation in C:\calibrant-relay\.previous and restores it automatically if the selected version does not start and authenticate successfully.

Releases published before transactional health checks are not offered as rollback targets, even if their old ZIP still exists. For those versions, redeploy the relay or select a newer retained recovery version rather than accepting an unverified start.

In-place recovery is not guaranteed. If the updater cannot restore a working relay or PowerShell runtime, delete and redeploy the relay, grant the replacement Managed Identity, and rerun any interrupted scan. A result that existed only in the deleted VM's local outbox cannot be recovered. Calibrant does not require or promise a successful in-place runtime rollback during early access.

Checking what a relay is running

The Connections page shows each relay's current version, and the Updates panel shows the gap. From the command line:

az vm run-command invoke \
  --name calibrant-relay-vm \
  --resource-group calibrant-relay-rg \
  --command-id RunPowerShellScript \
  --scripts "Get-Content C:\calibrant-relay\.version; Get-Content C:\calibrant-relay\updater.log -Tail 20"

The updater log states plainly what it decided, for example Version 1.53 is published but not approved for this tenant - staying on 1.52.

Viewing relay logs

# Relay activity
az vm run-command invoke \
  --name calibrant-relay-vm \
  --resource-group calibrant-relay-rg \
  --command-id RunPowerShellScript \
  --scripts "Get-Content C:\calibrant-relay\relay.log -Tail 50"

# Error log, if the service will not start
az vm run-command invoke \
  --name calibrant-relay-vm \
  --resource-group calibrant-relay-rg \
  --command-id RunPowerShellScript \
  --scripts "Get-Content C:\calibrant-relay\relay-error.log -Tail 50"

Rotating the API key

The relay authenticates to Calibrant with a per-relay API key. That key lives in two places at once: Calibrant's database (as a SHA-256 hash) and the Windows service environment on your relay VM. Rotation means changing both, and the two changes cannot be made at the same instant.

There is no overlap window. A relay holds exactly one valid key. Generating a new one replaces the old hash in place, so the old key stops working the moment you click the button — before you have set anything on the VM. Rotation is therefore a short, deliberate outage, not a seamless cutover. Plan for a few minutes with the relay offline, and do not start one while a scan is running.

There is no rollback to the previous key. Calibrant stores only a hash, so the old value cannot be recovered by us or by you. If the new key is lost between the portal and the VM, the recovery is to generate another key and set that one — not to go back. Keep the new key in your clipboard or password manager until the relay is confirmed online.

Before you rotate

Do these first, while the relay is still working. Each one is something you will not be able to do easily once the key is invalidated.

Confirm the relay is currently Online on Connections → Calibrant Relay, and that no scan is in progress. A relay that was already offline will not tell you whether the rotation worked.
Capture the Managed Identity client ID — you have to pass it back when you rewrite the service environment:
```
az identity show --name calibrant-relay-identity --resource-group calibrant-relay-rg --query clientId -o tsv
```

Verify you can reach the VM before you need to:

az vm run-command invoke \
  --name calibrant-relay-vm \
  --resource-group calibrant-relay-rg \
  --command-id RunPowerShellScript \
  --scripts "(Get-Service CalibrantRelay, CalibrantRelayUpdater).Status"

Both should report Running. If this command fails, fix that first — otherwise you will discover it with a dead relay.

Step 1 — Generate the new key

Go to Connections → Calibrant Relay, click the key icon on your deployment, and confirm. The value is shown once, because Calibrant keeps only a hash of it — copy it before closing the dialog.

From this moment the relay can no longer authenticate. Its Windows service keeps running and keeps polling — it just gets rejected every time — so Get-Service will still say Running. The Connections page is the honest signal, and it lags: a relay is shown Online for 15 minutes after its last successful check-in, so it will not flip to Offline immediately. Do not read that delay as the rotation having worked.

Step 2 — Set it on the VM, on both services

Two services need the key. The relay and the updater run as separate Windows services under NSSM, and both authenticate to Calibrant — the relay to collect scan work, the updater to ask which version you have approved. Set it on one only and you get the worst outcome: the relay looks healthy while updates stop arriving silently, including security fixes.

AppEnvironmentExtra also replaces the whole extra block rather than merging into it, so pass every variable back. The API key is the one value that lives only there — the others are also set at machine scope.

az vm run-command invoke \
  --name calibrant-relay-vm \
  --resource-group calibrant-relay-rg \
  --command-id RunPowerShellScript \
  --scripts "
    nssm set CalibrantRelay AppEnvironmentExtra `
      'CALIBRANT_API_URL=https://www.calibrant.ai' `
      'CALIBRANT_API_KEY=cal_YourNewKeyHere' `
      'POLL_INTERVAL_MS=600000' `
      ('AZURE_CLIENT_ID=' + [System.Environment]::GetEnvironmentVariable('AZURE_CLIENT_ID', 'Machine'))

    nssm set CalibrantRelayUpdater AppEnvironmentExtra `
      'CALIBRANT_API_URL=https://www.calibrant.ai' `
      'CALIBRANT_API_KEY=cal_YourNewKeyHere'

    Restart-Service CalibrantRelay -Force
    Restart-Service CalibrantRelayUpdater -Force
    (Get-Service CalibrantRelay, CalibrantRelayUpdater).Status
  "

The AZURE_CLIENT_ID expression above reads the machine-scope copy, so you do not have to paste the value. If your VM predates that machine-scope variable, substitute the client ID you captured before you started.

Step 3 — Confirm the relay accepted it

Do not skip this, and do not use the key prefix in the portal as your proof. That prefix comes from Calibrant's own record of the key it now expects, so it changes the instant you generate a new key whether or not the VM ever received it. It tells you nothing about the VM.

Two positive acknowledgements, one per service. Both come from the relay side:

The relay service. On startup it performs a health check against Calibrant and prints the first eight characters of the key it is actually using. Those eight characters must be a prefix of the twelve shown on the Connections page. On the Connections page, Last seen should advance to seconds ago:
```
az vm run-command invoke \
  --name calibrant-relay-vm \
  --resource-group calibrant-relay-rg \
  --command-id RunPowerShellScript \
  --scripts "Get-Content C:\calibrant-relay\relay.log -Tail 20"
```
The updater service. Within five minutes its log must show a version decision — for example Version 1.53 is published but not approved for this tenant - staying on 1.52. Update check failed is exactly what a stale key on the updater looks like:
```
az vm run-command invoke \
  --name calibrant-relay-vm \
  --resource-group calibrant-relay-rg \
  --command-id RunPowerShellScript \
  --scripts "Get-Content C:\calibrant-relay\updater.log -Tail 20"
```

If it did not work

The relay service exits on a failed startup health check rather than polling with a key it knows is bad, so a wrong key shows up as a service that will not stay running. Check the error log:

az vm run-command invoke \
  --name calibrant-relay-vm \
  --resource-group calibrant-relay-rg \
  --command-id RunPowerShellScript \
  --scripts "Get-Content C:\calibrant-relay\relay-error.log -Tail 30"

Health check failed followed by Check your CALIBRANT_API_URL and CALIBRANT_API_KEY means the value on the VM and the value Calibrant expects do not match. Recovery, in order of preference:

You still have the new key. Re-run Step 2 — a typo or a dropped quote in the AppEnvironmentExtra block is the usual cause.
You lost the new key. Generate another one and run Step 2 with that. There is no penalty for rotating twice, and no way to recover either previous value.
You cannot reach the VM at all. Redeploying the relay with the Bicep template passes the key in as a parameter, so a redeploy also resolves it. See Relay Setup.

Because there is only ever one valid key, no separate revocation step is needed — generating the replacement is the revocation of the old one, and it takes effect immediately. If you are rotating because a key was exposed, that exposure ends at Step 1, not at the end of this procedure.

Rotating because the VM itself may be compromised? A new API key is not enough. Anyone who can run code on that VM can also read the new key out of the service environment, and can request Managed Identity tokens for your tenant regardless of the key. Treat that case as an offboarding: delete the resource group and redeploy. See Removing the Relay.

Troubleshooting

An approved update has not installed — the relay checks every 5 minutes. Check updater.log (above); it names the reason on every cycle.
"Update check failed" in the log — the VM could not reach Calibrant, or the API key is wrong. Nothing installs when the check fails, by design. Verify the key as above.

Service will not start — check the error log:

az vm run-command invoke --name calibrant-relay-vm --resource-group calibrant-relay-rg --command-id RunPowerShellScript --scripts "Get-Content C:\calibrant-relay\relay-error.log -Tail 30"

Relay shows Offline after an update — wait 30 seconds and refresh. If still offline, check Get-Service CalibrantRelay and the error log. The updater normally restores the retained previous installation automatically. If it cannot, check updater.log and C:\calibrant-relay\.previous, then re-approve a listed Recovery version or use the documented delete-and-redeploy recovery path.