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. The dialog requires at least one scope, and empty-scope keys — legacy keys, or keys created against the Auth Service API — cannot register agents. A full-access (*) key also enrolls, but the dialog no longer offers it
3. Copy the secret once (ak_…) and store it in a secrets manager. Prefer one key per agent or pipeline

The key’s Access level decides which scopes it may carry. Project access 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 — but Project access hides register_agents in the picker, so choose Organization access when you are minting an enrollment key. Organization access also lets the key 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.

Revoking or restoring an agent is an Organization Owner action. It is not a project-level permission, so it cannot be delegated to a project role or carried by an API key — see API Keys.

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 pick a Harness Type (Claude Code, OpenCode, OpenClaw, Codex, or Proxy). The harness sets the --app value in the registration command
4. Governance Studio mints a short-lived token and shows two commands: Registration command, a viper did register that carries --provisioning-token, and Browser login alternative, the same command without the token, which mints its own through a browser login to Guardian (Viper must have guardian_url configured). Run whichever one suits the machine the agent lives on

The token lasts 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