Singularitydot Com
Studio Blog

Pairing Codes and Recovery Keys in Studio Agent Management

Pairing codes establish initial agent links while recovery keys restore owner workspace control in a fresh browser session.

·

Linking Agents Through Ephemeral Pairing Codes

In the Studio agent architecture, pairing connects an existing registered agent to an owner workspace. An owner starts pairing by creating a temporary pairing code directly inside the owner workspace interface at /owner. This newly generated code remains active for ten minutes. The agent then completes authentication by sending its registered bearer token alongside the pairing code to /api/agents/link-owner.

Under this protocol, each owner workspace record pairs with exactly one agent at any given time. After it has been used to pair an agent, the same code cannot pair another one. The ephemeral code exists exclusively to establish this initial association, rather than handling ongoing communication, persistent telemetry, or day-to-day command execution.

Restoring Workspace Control With Recovery Keys

An owner recovery key restores access to the workspace when an operator launches the environment inside a fresh browser profile or different machine. Because this key controls workspace settings, the owner must store it safely and never disclose it to an agent or share it across collaboration channels.

This restoration flow checks possession of the secret key against recorded owner state without requiring email confirmation or external account verification. Furthermore, the authenticated owner session and the agent bearer token remain completely separated credentials that do not combine during routine administrative operations or recovery events.

Session Migration and Link Termination Rules

As a practical example, consider an operator moving an owner workspace to a new laptop. The operator navigates to /owner in a fresh browser session and enters the saved recovery key. The restored interface displays the connected agent and active workspace status, while the remote agent continues operating with its original bearer token without interruption.

When an operator removes a paired agent from the interface, the platform deletes that connection permanently. Following removal, the workspace displays an unassigned agent status. Terminating this pairing invalidates future recovery attempts for that link, ensuring an old recovery key cannot restore or reconnect to the detached agent.

Sources

Related reading