Skip to main content
Agent keys can be rotated through the console without an observability gap. The cloud accepts both the new key and the previous key for 24 hours, so the deployment can roll over without strict synchronisation.

​
Steps

1

Generate a new key

In the console, open Agents, select the agent, then Rotate key. The cloud:
  1. Generates a new key, stores a hash of it, and returns the plaintext once.
  2. Retains the previous key’s hash, so the previous key keeps working for 24 hours. To cut it off at once (for example after a leak), tick Invalidate the old key immediately when rotating.
Copy the new key.You can also rotate through the API with POST /agents/{id}/rotate-key (scope write:agents). The response carries the new key once, with the agent’s environment variables already containing it. Add ?target= (docker, compose, kubernetes, systemd, launchd or binary) to also get that install command with the key filled in, or ?include=install for all of them. Send {"invalidate_immediately": true} to cut off the old key at once.
2

Or deliver the key through a claim link (optional)

When the key should not appear in the API response, for example because the caller is an AI assistant or a CI job whose output is logged, add ?delivery=claim. The key is rotated the same way, grace window included, but the response holds no key:
Open claim_url while signed in to the console as a member of the organization and select Reveal key to see the new key and its install command. The link works once and expires after 15 minutes. It also stops working if the key is rotated again or a newer claim link is issued for the same agent. Observer keeps the key only in encrypted form until it is revealed.POST /agents?delivery=claim creates an agent the same way.
3

Deploy the new key

Update the agent’s AGENT_KEY environment variable to the new value. The deployment path depends on your runtime:
  • Docker: docker run -e AGENT_KEY=<new> and restart the container.
  • Kubernetes: update the observer-agent Secret and roll the Deployment (kubectl rollout restart deploy/observer-agent).
  • systemd: edit /etc/observer-agent.env, then systemctl restart observer-agent.
  • launchd (macOS): edit AGENT_KEY in ~/Library/LaunchAgents/use.observer.agent.plist, then load it again (launchctl bootout gui/$(id -u)/use.observer.agent, then launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/use.observer.agent.plist).
The agent reconnects with the new key on its next heartbeat.
4

Confirm the rotation took effect

Open the agent’s dashboard. The Cloud panel reports a successful heartbeat with the new key. The Agents page in the console shows the agent as Running.
5

Retire the old key

The previous key keeps working for 24 hours, then becomes invalid automatically. To end the grace period on an earlier rotation, rotate again with Invalidate the old key immediately ticked and deploy the newest key. Subsequent requests with the previous key are rejected.

​
What the cloud sees

  • The cloud stores a hash of each key, never the plaintext.
  • The cloud stores a hash of the new key and retains the previous key’s hash for the grace window.
  • A request with the new key succeeds. A request with the previous key succeeds only until the grace window ends.
  • A lost key cannot be recovered. Rotate to issue a replacement.
Rotate after every secret-handling incidentTreat agent keys with the same care as any service credential. Rotate when an environment file is shared, when a developer with access leaves, or when a host’s image is exported. The grace window makes rotation cheap; do it often.