Register Agents

About registering agents

Registration creates a gateway agent under your user account and attaches your local signing DID. Guardian mints the agent ID (urn:uuid:) — you do not choose it.

Enrollment is not the same as putting an agent on a project. After the agent is registered, associate it in Governance Studio when you need project policy to apply to it, or when you want to see its traffic in the project.

You need the Register Agents permission. Organization Owners have it, and you can also assign the organization-level Agent Operator role. Learn more about Roles and Permissions.

Headless: API key and Viper

Use this path for CI, remote shells, and fleets.

1. Generate an enrollment key

From User Profile → API Keys:

1. Generate a key with a short expiration
2. Select the Register Agents scope. Empty scopes impersonate you in Governance Studio workflows, but they cannot register agents. Full access (*) also enrolls, and is available to Organization Owners only
3. Copy the secret once (ak_…) and store it in a secrets manager. Prefer one key per agent or pipeline

The Project dropdown locks project-level access, such as viewing project data. Registering agents is an organization-level action, so a key bound to one project can still enroll. Choose Organization only when the key should use its project-level permissions on every project you can already access.

API keys cannot create other API keys, so generate this key while signed in.

2. Register

Create or assign a local DID, then register. Prefer the environment variable so the secret does not appear on the command line, and do not put the key in Viper’s config file.

viper did add --assign proxy

GUARDIAN_API_KEY=ak_… viper did register --app proxy --agent-name "checkout-bot"

Viper prints the DID and the server-minted agent ID (urn:uuid:). One key can enroll more than one agent. Revoking the key stops new enrollments; agents already enrolled stay active until you revoke the agent.

After a successful registration, start a proxy or wrapper (viper proxy, viper claude, and so on) and point the agent at that URL. The enrollment key is not a traffic credential.

Governance Studio: registration token

Use this path when you are at a browser.

1. Open Gateway Agents
2. Select Register Agent
3. Enter an agent name and the Viper app (Claude, Codex, OpenCode, or Proxy)
4. Governance Studio mints a short-lived token and copies a viper did register command. Run it locally, or omit --provisioning-token to complete registration through the browser handoff (Viper must have guardian_url configured)

The token lasts about 15 minutes and works once. Governance Studio does not register the agent for you; it mints the token and the ID.

After you register

Associate the agent with a project from the project’s agent view by selecting Associate Agent. That step requires the Create Agent Memberships permission, held by Project Owners and Organization Owners. Until you associate it, the agent can still send traffic, but Governance Studio’s project views will not show it and project policies will not apply to it.

Related

• API Keys — generate, scope, bind to a project, and revoke keys
• Roles and Permissions — the Agent Operator role and the Register Agents permission