Updating the Relay

When Calibrant publishes a new relay version, you need to download the latest package and restart the Windows Service. The update takes about 2 minutes.

Option 1 — Azure Run Command (recommended, no RDP needed)

Run this from your local terminal. It executes PowerShell on the VM remotely and streams the output back to you — no RDP or SSH required:

az vm run-command invoke \
  --name calibrant-relay-vm \
  --resource-group calibrant-relay-rg \
  --command-id RunPowerShellScript \
  --scripts "
    Stop-Service CalirantRelay
    Invoke-WebRequest -Uri 'https://github.com/fusedad/calibrant/releases/download/relay-latest/calibrant-relay.zip' \
      -OutFile C:\calibrant-relay-update.zip -UseBasicParsing
    Remove-Item C:\calibrant-relay\dist -Recurse -Force -ErrorAction SilentlyContinue
    Remove-Item C:\calibrant-relay\node_modules -Recurse -Force -ErrorAction SilentlyContinue
    Expand-Archive -Path C:\calibrant-relay-update.zip -DestinationPath C:\calibrant-relay -Force
    Remove-Item C:\calibrant-relay-update.zip
    Start-Service CalirantRelay
    (Get-Service CalirantRelay).Status
  "

When it completes you'll see Running in the output. The relay will reconnect to Calibrant within 30 seconds and show green in Connections → Calibrant Relay.

Option 2 — RDP / PowerShell remoting

If you prefer to connect directly, open a PowerShell session on the VM and run:

Stop-Service CalirantRelay
Invoke-WebRequest -Uri 'https://github.com/fusedad/calibrant/releases/download/relay-latest/calibrant-relay.zip' `
  -OutFile C:calibrant-relay-update.zip -UseBasicParsing
Remove-Item C:calibrant-relaydist -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item C:calibrant-relay
ode_modules -Recurse -Force -ErrorAction SilentlyContinue
Expand-Archive -Path C:calibrant-relay-update.zip -DestinationPath C:calibrant-relay -Force
Remove-Item C:calibrant-relay-update.zip
Start-Service CalirantRelay
Get-Service CalirantRelay

Viewing relay logs

# Stream relay logs in real time (Ctrl+C to stop)
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"

# View error log if the service won't 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

Go to Connections → Calibrant Relay, click the key icon on your deployment, and generate a new key. Then update it on the VM:

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

Troubleshooting

• Service won't 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 update — wait 30 seconds and refresh. If still offline, check that the service is running: Get-Service CalirantRelay. If stopped, check the error log.
• Node.js error on startup — the update may have extracted files over a running process. Stop the service first, then update, then start again (the command above already does this in order).