dome agents

dome agents registers the agents a workspace governs and manages their lifecycle, the rules assigned to them, and the API keys they authenticate with. An agent must be registered before the Gateway will authorize anything it calls. Refer to Agents for the concept model.

Register agent

dome agents register

Register a new agent in the current workspace. Pass fields with per-field flags or load the full definition from a JSON/YAML file with --file.

dome agents register --name <name> [flags]
dome agents register --file <path>

Populating --pool, --model, --tool, --gateway, or an act-as access field triggers generation of an agent-scope kind='generated' rule bundle permitting or restricting the corresponding actions. Registering with any of these fields requires rules.deploy in addition to agents.register. Leaving all three --actas-allowed-* lists empty means "any verified identity is acceptable"; populating any one restricts the agent via a forbid-unless rule.

Identity-only registration needs agents.register alone.

* Provide either --name (per-field mode) or --file. The two modes cannot be combined.

Register from a file

Use --file to register from a single JSON or YAML document. The file shape mirrors the RegisterAgentRequest proto — the same schema the SDKs and Terraform provider consume — so a typo in a field name fails fast rather than silently dropping. The workspace is always taken from the active context; a workspace_id in the file is ignored.

name: claude-research
allowed_pool_names: [openai-prod]
allowed_tools: [github/list_repos]
actas_config:
  method: oidc
  required: true
  oidc_discovery_url: https://idp.example.com

dome agents register --file agent.yaml

# JSON works too
dome agents register -f agent.json

# Read from stdin
printf '{"name":"x"}' | dome agents register -f -

List agents

dome agents list

List agents in the current workspace.

dome agents list [flags]

Get agent

dome agents get [name-or-id]

Get details for a specific agent. Pass --gateway <id> to select an accessible Gateway and include its complete protocol endpoints. Without the flag, the command returns agent metadata only.

Name:    data-pipeline-agent
ID:      a1b2c3d4-…
Status:  active
Gateway ID:  {{GATEWAY_ID}}
Gateway URL: https://gateway.example.dome.dev/gateways/{{GATEWAY_ID}}
MCP URL:     https://gateway.example.dome.dev/gateways/{{GATEWAY_ID}}/mcp

Update agent

dome agents update [name-or-id]

Update an agent's metadata, token lifetime, allowed resources, or act-as config.

The --pool, --model, --tool, and --actas-allowed-* flags use PUT semantics: whatever you send IS the new state, including an empty value meaning "clear". To update only one field, get the agent first and pass the current values back.

Changing any of these four-pillar fields (or --actas-method / --actas-required) regenerates the agent's kind='generated' rule bundle and therefore requires the rules.deploy permission in addition to agents.register. Identity-only updates (name, metadata, token TTL) pass through on agents.register alone.

Lifecycle

Suspend agent

dome agents suspend [name-or-id]

Suspend an agent temporarily.

Reactivate agent

dome agents reactivate [name-or-id]

Reactivate a suspended agent.

Revoke agent

dome agents revoke [name-or-id]

Permanently revoke an agent. Always cascades to all descendants.

Delete agent

dome agents delete [name-or-id]

Permanently hard-delete a revoked agent and all its data. Requires the agent to be in a revoked state.

Rules

Assign policy

dome agents assign-policy [name-or-id] [files...]

Deploy Cedar rules scoped to a specific agent.

Get policies

dome agents get-policies [name-or-id]

Get Cedar rules assigned to an agent.

API keys

Create key

dome agents create-key [name-or-id]

Create an agent authentication key. Prints the token and the selected Gateway's complete endpoints once.

✓ API key "default" created for agent my-first-agent
✓ Token: dome_…
Gateway ID:  {{GATEWAY_ID}}
Gateway URL: https://gateway.example.dome.dev/gateways/{{GATEWAY_ID}}
MCP URL:     https://gateway.example.dome.dev/gateways/{{GATEWAY_ID}}/mcp
ℹ Save this token — it will not be shown again.

Use the URL for the protocol your application speaks. JSON output returns gatewayId and gatewayEndpoints.

List keys

dome agents list-keys [name-or-id]

List API keys for an agent.

Rotate key

dome agents rotate-key [name-or-id] [key-name]

Rotate an agent's API key — revokes the old secret and issues a new one. Use --gateway <id> to select the Gateway when the agent can access more than one. Output includes gatewayId and gatewayEndpoints.

Revoke key

dome agents revoke-key [name-or-id] [key-name]

Revoke an agent's API key permanently.

Interactive access

Set --interactive-access only when human MCP clients should ride this agent. Interactive access requires at least one --actas-allowed-email or --actas-allowed-subject; matching is exact and case-sensitive.

Interactive access is mutually exclusive with device binding. Group allow-lists do not match interactive logins. Human traffic spends the selected agent's Quotas.

List interactive grants

dome agents interactive-grants list

List grants owned by the signed-in person. This self-service view requires no workspace permission.

dome agents interactive-grants list --all-users
dome agents interactive-grants list --agent <name-or-id>

List all grants in the active workspace with --all-users. This requires agents.view. --agent filters the workspace result and implies --all-users.

A platform API key has no personal grants. Use --all-users with a workspace-, tenant-, or org-scoped key that grants agents.view.

The output contains grant IDs, agent and client identity, status, creation, last use, expiration, and refresh count. It never returns tokens or secret material.

Revoke interactive grant

dome agents interactive-grants revoke <grant-id>

Revoke the refresh-token family immediately. The current access token remains usable only until its short expiry.

Anyone can revoke their own grant. Revoking another person's grant requires agentkeys.manage on the grant's workspace. A platform API key always uses this administrator path.