# Create Agent Key
Source: https://docs.domesystems.ai/api/agents/create-agent-key
POST /dome.agent.v1.AgentRegistry/CreateAgentKey
# Delete Agent
Source: https://docs.domesystems.ai/api/agents/delete-agent
POST /dome.agent.v1.AgentRegistry/DeleteAgent
# Get Agent
Source: https://docs.domesystems.ai/api/agents/get-agent
POST /dome.agent.v1.AgentRegistry/GetAgent
# List Agent Keys
Source: https://docs.domesystems.ai/api/agents/list-agent-keys
POST /dome.agent.v1.AgentRegistry/ListAgentKeys
# List Agents
Source: https://docs.domesystems.ai/api/agents/list-agents
POST /dome.agent.v1.AgentRegistry/ListAgents
# Reactivate Agent
Source: https://docs.domesystems.ai/api/agents/reactivate-agent
POST /dome.agent.v1.AgentRegistry/ReactivateAgent
# Register Agent
Source: https://docs.domesystems.ai/api/agents/register-agent
POST /dome.agent.v1.AgentRegistry/RegisterAgent
# Revoke Agent
Source: https://docs.domesystems.ai/api/agents/revoke-agent
POST /dome.agent.v1.AgentRegistry/RevokeAgent
# Revoke Agent Key
Source: https://docs.domesystems.ai/api/agents/revoke-agent-key
POST /dome.agent.v1.AgentRegistry/RevokeAgentKey
# Rotate Agent Key
Source: https://docs.domesystems.ai/api/agents/rotate-agent-key
POST /dome.agent.v1.AgentRegistry/RotateAgentKey
# Suspend Agent
Source: https://docs.domesystems.ai/api/agents/suspend-agent
POST /dome.agent.v1.AgentRegistry/SuspendAgent
# Update Agent
Source: https://docs.domesystems.ai/api/agents/update-agent
POST /dome.agent.v1.AgentRegistry/UpdateAgent
# Get Event
Source: https://docs.domesystems.ai/api/audit/get-event
POST /dome.audit.v1.Audit/GetEvent
# Ingest Events
Source: https://docs.domesystems.ai/api/audit/ingest-events
POST /dome.audit.v1.Audit/IngestEvents
# Query Events
Source: https://docs.domesystems.ai/api/audit/query-events
POST /dome.audit.v1.Audit/QueryEvents
# Stream Events
Source: https://docs.domesystems.ai/api/audit/stream-events
POST /dome.audit.v1.Audit/StreamEvents
# Delete Rules
Source: https://docs.domesystems.ai/api/authorization/delete-rules
POST /dome.authz.v1.Authorization/DeleteRules
# Deploy Bundle
Source: https://docs.domesystems.ai/api/authorization/deploy-bundle
POST /dome.authz.v1.Authorization/DeployBundle
# Evaluate
Source: https://docs.domesystems.ai/api/authorization/evaluate
POST /dome.authz.v1.Authorization/Evaluate
# Explain Agent Capabilities
Source: https://docs.domesystems.ai/api/authorization/explain-agent-capabilities
POST /dome.authz.v1.Authorization/ExplainAgentCapabilities
# Get Agent Effective Policy
Source: https://docs.domesystems.ai/api/authorization/get-agent-effective-policy
POST /dome.authz.v1.Authorization/GetAgentEffectivePolicy
# Get Bundle
Source: https://docs.domesystems.ai/api/authorization/get-bundle
POST /dome.authz.v1.Authorization/GetBundle
# Get Workspace Policies
Source: https://docs.domesystems.ai/api/authorization/get-workspace-policies
POST /dome.authz.v1.Authorization/GetAllAgentsEffectivePoliciesForWorkspace
# List Bundles
Source: https://docs.domesystems.ai/api/authorization/list-bundles
POST /dome.authz.v1.Authorization/ListBundles
# Rollback Bundle
Source: https://docs.domesystems.ai/api/authorization/rollback-bundle
POST /dome.authz.v1.Authorization/RollbackBundle
# Validate Rules
Source: https://docs.domesystems.ai/api/authorization/validate-rules
POST /dome.authz.v1.Authorization/ValidateRules
# Add Gateway LLM model
Source: https://docs.domesystems.ai/api/gateway/add-gateway-llm-model
POST /dome.gateway.v1.GatewayService/AddGatewayLLMModel
# Add Gateway LLM pool
Source: https://docs.domesystems.ai/api/gateway/add-gateway-llm-pool
POST /dome.gateway.v1.GatewayService/AddGatewayLLMPool
# Add Gateway tool
Source: https://docs.domesystems.ai/api/gateway/add-gateway-tool
POST /dome.gateway.v1.GatewayService/AddGatewayTool
# Add Gateway tool source
Source: https://docs.domesystems.ai/api/gateway/add-gateway-tool-source
POST /dome.gateway.v1.GatewayService/AddGatewayToolSource
# Create Gateway
Source: https://docs.domesystems.ai/api/gateway/create-gateway
POST /dome.gateway.v1.GatewayService/CreateGateway
# Delete Gateway
Source: https://docs.domesystems.ai/api/gateway/delete-gateway
POST /dome.gateway.v1.GatewayService/DeleteGateway
# Get Gateway
Source: https://docs.domesystems.ai/api/gateway/get-gateway
POST /dome.gateway.v1.GatewayService/GetGateway
# List Gateways
Source: https://docs.domesystems.ai/api/gateway/list-gateways
POST /dome.gateway.v1.GatewayService/ListGateways
# Remove Gateway LLM model
Source: https://docs.domesystems.ai/api/gateway/remove-gateway-llm-model
POST /dome.gateway.v1.GatewayService/RemoveGatewayLLMModel
# Remove Gateway LLM pool
Source: https://docs.domesystems.ai/api/gateway/remove-gateway-llm-pool
POST /dome.gateway.v1.GatewayService/RemoveGatewayLLMPool
# Remove Gateway tool
Source: https://docs.domesystems.ai/api/gateway/remove-gateway-tool
POST /dome.gateway.v1.GatewayService/RemoveGatewayTool
# Remove Gateway tool source
Source: https://docs.domesystems.ai/api/gateway/remove-gateway-tool-source
POST /dome.gateway.v1.GatewayService/RemoveGatewayToolSource
# Set Gateway all-agents grant
Source: https://docs.domesystems.ai/api/gateway/set-gateway-all-agents-grant
POST /dome.gateway.v1.GatewayService/SetGatewayAllAgentsGrant
# Set Gateway default
Source: https://docs.domesystems.ai/api/gateway/set-gateway-default
POST /dome.gateway.v1.GatewayService/SetGatewayDefault
# Set Gateway state
Source: https://docs.domesystems.ai/api/gateway/set-gateway-state
POST /dome.gateway.v1.GatewayService/SetGatewayState
# Update Gateway
Source: https://docs.domesystems.ai/api/gateway/update-gateway
POST /dome.gateway.v1.GatewayService/UpdateGateway
# Exchange Token
Source: https://docs.domesystems.ai/api/identity/exchange-token
POST /dome.identity.v1.Identity/ExchangeToken
# API Reference
Source: https://docs.domesystems.ai/api/index
Connect RPC API for the Dome Platform
The Dome Platform exposes a Connect RPC API organized into six services. Each service covers a distinct domain — agent registry, identity, authorization, audit, platform management, and simulation.
All endpoints use `POST` with JSON request bodies. Authentication is via Bearer token from the [Identity service](/api/identity/exchange-token).
Register, update, suspend, revoke agents and manage API keys.
Token exchange and authentication.
Deploy, evaluate, and manage Cedar rule bundles.
Query, stream, and export audit events.
Workspaces, backends, verification providers, and platform config.
Replay candidate rules against audit history.
## Next steps
Same operations show up in the CLI and MCP. Runtime calls go through Develop:
* [CLI](/cli) for the equivalent command-line surfaces
* [MCP](/reference/mcp) when an assistant should call the same operations
* [Develop](/develop) for runtime credentials and Gateway endpoints
* [Events](/reference/events) reference for audit envelope and catalog contracts
# Assign Role
Source: https://docs.domesystems.ai/api/management/assign-role
POST /dome.mgmt.v1.Management/AssignRole
# Begin LLM OAuth connect
Source: https://docs.domesystems.ai/api/management/begin-llm-oauth-connect
POST /dome.mgmt.v1.Management/BeginLLMOAuthConnect
# Begin MCP server OAuth connect
Source: https://docs.domesystems.ai/api/management/begin-mcp-server-oauth-connect
POST /dome.mgmt.v1.Management/BeginMCPServerOAuthConnect
# Check Tenant Permission
Source: https://docs.domesystems.ai/api/management/check-tenant-permission
POST /dome.mgmt.v1.Management/CheckTenantPermission
# Create API Key
Source: https://docs.domesystems.ai/api/management/create-api-key
POST /dome.mgmt.v1.Management/CreateAPIKey
# Create LLM model connection
Source: https://docs.domesystems.ai/api/management/create-llm-model-connection
POST /dome.mgmt.v1.Management/CreateLLMModelConnection
# Create LLM pool
Source: https://docs.domesystems.ai/api/management/create-llm-pool
POST /dome.mgmt.v1.Management/CreateLLMPool
# Create LLM pool member
Source: https://docs.domesystems.ai/api/management/create-llm-pool-member
POST /dome.mgmt.v1.Management/CreateLLMPoolMember
# Create LLM quota
Source: https://docs.domesystems.ai/api/management/create-llm-quota
POST /dome.mgmt.v1.Management/CreateLLMQuota
# Create MCP server connection
Source: https://docs.domesystems.ai/api/management/create-mcp-server-connection
POST /dome.mgmt.v1.Management/CreateMCPServerConnection
# Create Tenant
Source: https://docs.domesystems.ai/api/management/create-tenant
POST /dome.mgmt.v1.Management/CreateTenant
# Create Verification Provider
Source: https://docs.domesystems.ai/api/management/create-verification-provider
POST /dome.mgmt.v1.Management/CreateVerificationProvider
# Create Workspace
Source: https://docs.domesystems.ai/api/management/create-workspace
POST /dome.mgmt.v1.Management/CreateWorkspace
# Delete LLM model connection
Source: https://docs.domesystems.ai/api/management/delete-llm-model-connection
POST /dome.mgmt.v1.Management/DeleteLLMModelConnection
# Delete LLM pool
Source: https://docs.domesystems.ai/api/management/delete-llm-pool
POST /dome.mgmt.v1.Management/DeleteLLMPool
# Delete LLM pool member
Source: https://docs.domesystems.ai/api/management/delete-llm-pool-member
POST /dome.mgmt.v1.Management/DeleteLLMPoolMember
# Delete LLM quota
Source: https://docs.domesystems.ai/api/management/delete-llm-quota
POST /dome.mgmt.v1.Management/DeleteLLMQuota
# Delete MCP server connection
Source: https://docs.domesystems.ai/api/management/delete-mcp-server-connection
POST /dome.mgmt.v1.Management/DeleteMCPServerConnection
# Delete Tenant
Source: https://docs.domesystems.ai/api/management/delete-tenant
POST /dome.mgmt.v1.Management/DeleteTenant
# Delete Verification Provider
Source: https://docs.domesystems.ai/api/management/delete-verification-provider
POST /dome.mgmt.v1.Management/DeleteVerificationProvider
# Delete Workspace
Source: https://docs.domesystems.ai/api/management/delete-workspace
POST /dome.mgmt.v1.Management/DeleteWorkspace
# Disconnect LLM OAuth
Source: https://docs.domesystems.ai/api/management/disconnect-llm-oauth
POST /dome.mgmt.v1.Management/DisconnectLLMOAuth
# Disconnect MCP server OAuth
Source: https://docs.domesystems.ai/api/management/disconnect-mcp-server-oauth
POST /dome.mgmt.v1.Management/DisconnectMCPServerOAuth
# Get Config
Source: https://docs.domesystems.ai/api/management/get-config
POST /dome.mgmt.v1.Management/GetConfig
# Get Grantable Permissions
Source: https://docs.domesystems.ai/api/management/get-grantable-permissions
POST /dome.mgmt.v1.Management/GetGrantablePermissions
# Get LLM model connection
Source: https://docs.domesystems.ai/api/management/get-llm-model-connection
POST /dome.mgmt.v1.Management/GetLLMModelConnection
# Get LLM model connection credential
Source: https://docs.domesystems.ai/api/management/get-llm-model-connection-credential
POST /dome.mgmt.v1.Management/GetLLMModelConnectionCredential
# Get LLM pool
Source: https://docs.domesystems.ai/api/management/get-llm-pool
POST /dome.mgmt.v1.Management/GetLLMPool
# Get LLM pool member
Source: https://docs.domesystems.ai/api/management/get-llm-pool-member
POST /dome.mgmt.v1.Management/GetLLMPoolMember
# Get MCP server connection
Source: https://docs.domesystems.ai/api/management/get-mcp-server-connection
POST /dome.mgmt.v1.Management/GetMCPServerConnection
# Get MCP server connection credential
Source: https://docs.domesystems.ai/api/management/get-mcp-server-connection-credential
POST /dome.mgmt.v1.Management/GetMCPServerConnectionCredential
# Get Platform Status
Source: https://docs.domesystems.ai/api/management/get-platform-status
POST /dome.mgmt.v1.Management/GetPlatformStatus
# Get Tenant
Source: https://docs.domesystems.ai/api/management/get-tenant
POST /dome.mgmt.v1.Management/GetTenant
# Get User Role
Source: https://docs.domesystems.ai/api/management/get-user-role
POST /dome.mgmt.v1.Management/GetUserRole
# Get Verification Provider
Source: https://docs.domesystems.ai/api/management/get-verification-provider
POST /dome.mgmt.v1.Management/GetVerificationProvider
# Get Workspace
Source: https://docs.domesystems.ai/api/management/get-workspace
POST /dome.mgmt.v1.Management/GetWorkspace
# Get Workspace Act-As
Source: https://docs.domesystems.ai/api/management/get-workspace-act-as
POST /dome.mgmt.v1.Management/GetWorkspaceActAs
# List API Keys
Source: https://docs.domesystems.ai/api/management/list-api-keys
POST /dome.mgmt.v1.Management/ListAPIKeys
# List Catalog Services
Source: https://docs.domesystems.ai/api/management/list-catalog-services
POST /dome.mgmt.v1.Management/ListCatalogServices
# List Egress Connections
Source: https://docs.domesystems.ai/api/management/list-egress-connections
POST /dome.mgmt.v1.Management/ListEgressConnections
# List Joinable Tenants
Source: https://docs.domesystems.ai/api/management/list-joinable-tenants
POST /dome.mgmt.v1.Management/ListJoinableTenants
# List LLM model connections
Source: https://docs.domesystems.ai/api/management/list-llm-model-connections
POST /dome.mgmt.v1.Management/ListLLMModelConnections
# List LLM pool members
Source: https://docs.domesystems.ai/api/management/list-llm-pool-members
POST /dome.mgmt.v1.Management/ListLLMPoolMembers
# List LLM pools
Source: https://docs.domesystems.ai/api/management/list-llm-pools
POST /dome.mgmt.v1.Management/ListLLMPools
# List LLM quotas
Source: https://docs.domesystems.ai/api/management/list-llm-quotas
POST /dome.mgmt.v1.Management/ListLLMQuotas
# List MCP server connections
Source: https://docs.domesystems.ai/api/management/list-mcp-server-connections
POST /dome.mgmt.v1.Management/ListMCPServerConnections
# List Tenants
Source: https://docs.domesystems.ai/api/management/list-tenants
POST /dome.mgmt.v1.Management/ListTenants
# List Users
Source: https://docs.domesystems.ai/api/management/list-users
POST /dome.mgmt.v1.Management/ListUsers
# List Verification Providers
Source: https://docs.domesystems.ai/api/management/list-verification-providers
POST /dome.mgmt.v1.Management/ListVerificationProviders
# List Workspace Memberships
Source: https://docs.domesystems.ai/api/management/list-workspace-memberships
POST /dome.mgmt.v1.Management/ListWorkspaceMemberships
# List Workspaces
Source: https://docs.domesystems.ai/api/management/list-workspaces
POST /dome.mgmt.v1.Management/ListWorkspaces
# Probe MCP server auth
Source: https://docs.domesystems.ai/api/management/probe-mcp-server-auth
POST /dome.mgmt.v1.Management/ProbeMCPServerAuth
# Provision Sandbox Tenant
Source: https://docs.domesystems.ai/api/management/provision-sandbox-tenant
POST /dome.mgmt.v1.Management/ProvisionSandboxTenant
# Provision Sandbox Workspace
Source: https://docs.domesystems.ai/api/management/provision-sandbox-workspace
POST /dome.mgmt.v1.Management/ProvisionSandboxWorkspace
# Remove Role
Source: https://docs.domesystems.ai/api/management/remove-role
POST /dome.mgmt.v1.Management/RemoveRole
# Remove Workspace Membership
Source: https://docs.domesystems.ai/api/management/remove-workspace-membership
POST /dome.mgmt.v1.Management/RemoveWorkspaceMembership
# Resolve Permissions
Source: https://docs.domesystems.ai/api/management/resolve-permissions
POST /dome.mgmt.v1.Management/ResolvePermissions
# Revoke API Key
Source: https://docs.domesystems.ai/api/management/revoke-api-key
POST /dome.mgmt.v1.Management/RevokeAPIKey
# Set default LLM pool
Source: https://docs.domesystems.ai/api/management/set-default-llm-pool
POST /dome.mgmt.v1.Management/SetDefaultLLMPool
# Set Workspace Membership
Source: https://docs.domesystems.ai/api/management/set-workspace-membership
POST /dome.mgmt.v1.Management/SetWorkspaceMembership
# Sync MCP server connection tools
Source: https://docs.domesystems.ai/api/management/sync-mcp-server-connection-tools
POST /dome.mgmt.v1.Management/SyncMCPServerConnectionTools
# Update Config
Source: https://docs.domesystems.ai/api/management/update-config
POST /dome.mgmt.v1.Management/UpdateConfig
# Update LLM model connection
Source: https://docs.domesystems.ai/api/management/update-llm-model-connection
POST /dome.mgmt.v1.Management/UpdateLLMModelConnection
# Update LLM pool
Source: https://docs.domesystems.ai/api/management/update-llm-pool
POST /dome.mgmt.v1.Management/UpdateLLMPool
# Update LLM pool member
Source: https://docs.domesystems.ai/api/management/update-llm-pool-member
POST /dome.mgmt.v1.Management/UpdateLLMPoolMember
# Update LLM quota
Source: https://docs.domesystems.ai/api/management/update-llm-quota
POST /dome.mgmt.v1.Management/UpdateLLMQuota
# Update MCP server connection
Source: https://docs.domesystems.ai/api/management/update-mcp-server-connection
POST /dome.mgmt.v1.Management/UpdateMCPServerConnection
# Update Verification Provider
Source: https://docs.domesystems.ai/api/management/update-verification-provider
POST /dome.mgmt.v1.Management/UpdateVerificationProvider
# Update Workspace Act-As
Source: https://docs.domesystems.ai/api/management/update-workspace-act-as
POST /dome.mgmt.v1.Management/UpdateWorkspaceActAs
# Update Workspace Freshness Window
Source: https://docs.domesystems.ai/api/management/update-workspace-freshness-window
POST /dome.mgmt.v1.Management/UpdateWorkspaceFreshnessWindow
# Update workspace LLM filter window
Source: https://docs.domesystems.ai/api/management/update-workspace-llm-filter-window
POST /dome.mgmt.v1.Management/UpdateWorkspaceLLMFilterWindow
# Get Result
Source: https://docs.domesystems.ai/api/simulation/get-result
POST /dome.simulation.v1.Simulation/GetResult
# Simulate
Source: https://docs.domesystems.ai/api/simulation/simulate
POST /dome.simulation.v1.Simulation/Simulate
# dome agents
Source: https://docs.domesystems.ai/cli/connect/agents
Manage agent registrations, lifecycle, and API keys
| Command | |
| ------------------------------- | --------------------------------------------------- |
| [Register](#register) | `dome agents register` |
| [List](#list) | `dome agents list` |
| [Get](#get) | `dome agents get [name-or-id]` |
| [Update](#update) | `dome agents update [name-or-id]` |
| [Suspend](#suspend) | `dome agents suspend [name-or-id]` |
| [Reactivate](#reactivate) | `dome agents reactivate [name-or-id]` |
| [Revoke](#revoke) | `dome agents revoke [name-or-id]` |
| [Delete](#delete) | `dome agents delete [name-or-id]` |
| [Create key](#create-key) | `dome agents create-key [name-or-id]` |
| [List keys](#list-keys) | `dome agents list-keys [name-or-id]` |
| [Rotate key](#rotate-key) | `dome agents rotate-key [name-or-id] [key-name]` |
| [Revoke key](#revoke-key) | `dome agents revoke-key [name-or-id] [key-name]` |
| [Assign-policy](#assign-policy) | `dome agents assign-policy [name-or-id] [files...]` |
| [Get-policies](#get-policies) | `dome agents get-policies [name-or-id]` |
***
## Register
`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`.
```bash theme={"system"}
dome agents register --name [flags]
dome agents register --file
```
| Flag | Type | Required | Description |
| ------------------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--file`, `-f` | string | Yes\* | Path to a JSON/YAML file with the full agent definition. Use `-` for stdin. Mutually exclusive with per-field flags |
| `--name` | string | Yes\* | Agent name |
| `--capabilities` | string\[] | No | Custom capability strings (repeatable). System capabilities `llm:invoke`, `mcp:call`, and `mcp:discover` are derived automatically from the selections below |
| `--parent-id` | string | No | Parent agent ID |
| `--metadata` | key=value | No | Agent metadata (repeatable) |
| `--if-not-exists` | bool | No | Return existing agent if name is taken |
| `--pool` | string\[] | No | LLM pool the agent may route to (repeatable). Emits a `permit` against `Dome::LLMModel` matched via `resource.pool == ""` in the agent's generated bundle |
| `--model` | string\[] | No | LLM model connection the agent may invoke directly (repeatable, advanced — pools are preferred). Emits a `permit` against `Dome::LLMModel` |
| `--tool` | string\[] | No | MCP tool the agent may call, as `/` (repeatable). Emits `mcp:call` and `mcp:discover` permits against `Dome::MCPTool` |
| `--gateway` | string\[] | No | [Gateway](/connect/gateways) ID (UUID) the agent may reach (repeatable). Admits the agent at the Gateway endpoint and generates a membership-conditioned permit. |
| `--actas-allowed-group` | string\[] | No | Group the agent's verified act-as identity may belong to (repeatable). Emits a `forbid` unless the verified group matches |
| `--actas-allowed-email` | string\[] | No | Email the agent may act on behalf of (repeatable). Emits a `forbid` unless the verified email matches |
| `--actas-allowed-subject` | string\[] | No | Subject the agent may act on behalf of (repeatable). Emits a `forbid` unless the verified subject matches |
| `--actas-method` | string | No | Act-as verification: `none`, `oidc`, `hmac` |
| `--actas-required` | bool | No | Require act-as header on every request |
| `--actas-provider` | string | No | Workspace verification provider ID |
| `--actas-oidc-url` | string | No | Inline OIDC discovery URL |
| `--actas-hmac-secret` | string | No | Inline HMAC shared secret |
| `--actas-config-name` | string | No | Label for agent-specific verification config |
| `--pool` | string\[] | No | LLM pool name the agent may route to (repeatable) |
| `--model` | string\[] | No | LLM model connection name the agent may invoke directly (advanced; repeatable) |
| `--tool` | string\[] | No | MCP tool the agent may call as `/` (repeatable) |
| `--actas-allowed-group` | string\[] | No | Group claim the agent's verified act-as identity may belong to (repeatable) |
| `--actas-allowed-email` | string\[] | No | Email the agent may act on behalf of (repeatable) |
| `--actas-allowed-subject` | string\[] | No | Subject the agent may act on behalf of (repeatable) |
Populating `--pool`, `--model`, or `--tool` triggers generation of an agent-scope `kind='generated'` rule bundle and auto-derives the corresponding capabilities (`llm:invoke`, `mcp:call`, `mcp:discover`). Leaving all three `--actas-allowed-*` lists empty means "any verified identity is acceptable"; populating any one restricts the agent via a forbid-unless rule.
Pool, model, tool, and `--actas-allowed-*` flags populate the agent's generated rule bundle. Update operations that change any of these fields require `rules.deploy` in addition to `agent.register`.
\* 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.
```yaml agent.yaml theme={"system"}
name: claude-research
capabilities: [read]
allowed_pool_names: [openai-prod]
allowed_tools: [github/list_repos]
actas_config:
method: oidc
required: true
oidc_discovery_url: https://idp.example.com/.well-known/openid-configuration
```
```bash theme={"system"}
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
`dome agents list`
List agents in the current workspace.
```bash theme={"system"}
dome agents list [flags]
```
| Flag | Type | Description |
| ---------- | ------ | ----------------------------------------------------------------- |
| `--status` | string | Filter by status: `active`, `provisioned`, `suspended`, `revoked` |
| `--limit` | int | Maximum results (default: 100) |
## Get
`dome agents get [name-or-id]`
Get details for a specific agent. Pass `--gateway ` to select an accessible Gateway and include its complete protocol endpoints. Without the flag, the command returns agent metadata only.
```text Output theme={"system"}
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
```
| Flag | Type | Description |
| ----------- | ------ | ---------------------------------------------------------------------------------------------- |
| `--gateway` | string | Gateway ID used to resolve endpoints; required when the agent can access more than one Gateway |
## Update
`dome agents update [name-or-id]`
Update an agent's capabilities, metadata, or act-as config.
| Flag | Type | Description |
| ------------------------- | --------- | ------------------------------------------------------------------------------------ |
| `--capabilities` | string\[] | Updated custom capabilities |
| `--metadata` | key=value | Updated metadata |
| `--pool` | string\[] | Replace the agent's allowed LLM pool list |
| `--model` | string\[] | Replace the agent's allowed direct-model list |
| `--tool` | string\[] | Replace the agent's allowed MCP tool list (`/`) |
| `--gateway` | string\[] | Replace the agent's allowed [Gateway](/connect/gateways) ID list (UUIDs; repeatable) |
| `--actas-allowed-group` | string\[] | Replace the agent's act-as allowed-groups list |
| `--actas-allowed-email` | string\[] | Replace the agent's act-as allowed-emails list |
| `--actas-allowed-subject` | string\[] | Replace the agent's act-as allowed-subjects list |
| `--actas-method` | string | Act-as verification: `none`, `oidc`, `hmac` |
| `--actas-required` | bool | Require act-as header |
| `--actas-provider` | string | Workspace verification provider ID |
| `--actas-oidc-url` | string | Inline OIDC discovery URL |
| `--actas-hmac-secret` | string | Inline HMAC shared secret |
| `--actas-config-name` | string | Label for agent-specific verification config |
| `--pool` | string\[] | Replace the agent's allowed LLM pool list (repeatable) |
| `--model` | string\[] | Replace the agent's allowed direct-model list (advanced; repeatable) |
| `--tool` | string\[] | Replace the agent's allowed MCP tool list (repeatable; each `/`) |
| `--actas-allowed-group` | string\[] | Replace the agent's act-as allowed-groups list (repeatable) |
| `--actas-allowed-email` | string\[] | Replace the agent's act-as allowed-emails list (repeatable) |
| `--actas-allowed-subject` | string\[] | Replace the agent's act-as allowed-subjects list (repeatable) |
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 `agent.register`. Identity-only updates (name, metadata, capabilities) pass through on `agent.register` alone.
Changing any pool, model, tool, or `--actas-allowed-*` field regenerates the agent's rule bundle and requires `rules.deploy` in addition to `agent.register`. Identity-only updates (name, metadata, capabilities) require only `agent.register`.
## Suspend
`dome agents suspend [name-or-id]`
Suspend an agent temporarily.
| Flag | Type | Description |
| ----------- | ------ | ------------------------- |
| `--reason` | string | Suspension reason |
| `--cascade` | bool | Also suspend child agents |
## Reactivate
`dome agents reactivate [name-or-id]`
Reactivate a suspended agent.
## Revoke
`dome agents revoke [name-or-id]`
Permanently revoke an agent. Always cascades to all descendants.
| Flag | Type | Description |
| ---------- | ------ | ----------------- |
| `--reason` | string | Revocation reason |
## Delete
`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.
| Flag | Type | Description |
| ----------- | ------ | ----------------------------- |
| `--reason` | string | Deletion reason |
| `--cascade` | bool | Also delete descendant agents |
## 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.
## 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.
| Flag | Type | Required | Description |
| ----------- | ------ | -------- | ---------------------------------------------------------------------------------------------- |
| `--name` | string | Yes | Key name |
| `--gateway` | string | No | Gateway ID used to resolve endpoints; required when the agent can access more than one Gateway |
```text Output theme={"system"}
✓ 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 ` 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.
# dome gateway
Source: https://docs.domesystems.ai/cli/connect/gateway
Manage Gateways, their members, agent access grants, and cost quotas
`dome gateway` manages workspace-scoped groupings of callable resources — MCP tool connections, LLM pools, and direct LLM model connections — plus the agent access grants and cost caps that govern each grouping. Refer to [Gateways](/connect/gateways) for the concept model.
Resource-side mirrors live under [`dome tool gateways`](/cli/connect/tools#gateways) and [`dome model pool gateways`](/cli/connect/models#pool-gateways) (each with `list`, `add`, `remove`). Attach at create time with `--gateway` on `dome tool add`, `dome model add`, and `dome model pool create`.
| Command | |
| ------------------------------------------- | --------------------------------------------------------- |
| [List](#list) | `dome gateway list` |
| [Get](#get) | `dome gateway get ` |
| [Create](#create) | `dome gateway create ` |
| [Update](#update) | `dome gateway update ` |
| [Enable](#enable) | `dome gateway enable ` |
| [Disable](#disable) | `dome gateway disable ` |
| [Set default](#set-default) | `dome gateway set-default ` |
| [Delete](#delete) | `dome gateway delete ` |
| [Tools add](#tools-add) | `dome gateway tools add ` |
| [Tools remove](#tools-remove) | `dome gateway tools remove ` |
| [Tool-sources add](#tool-sources-add) | `dome gateway tool-sources add ` |
| [Tool-sources remove](#tool-sources-remove) | `dome gateway tool-sources remove ` |
| [Model-pools add](#model-pools-add) | `dome gateway model-pools add ` |
| [Model-pools remove](#model-pools-remove) | `dome gateway model-pools remove ` |
| [Models add](#models-add) | `dome gateway models add ` |
| [Models remove](#models-remove) | `dome gateway models remove ` |
| [Access list](#access-list) | `dome gateway access list ` |
| [Access grant](#access-grant) | `dome gateway access grant ` |
| [Access revoke](#access-revoke) | `dome gateway access revoke ` |
| [Access grant-all](#access-grant-all) | `dome gateway access grant-all ` |
| [Access revoke-all](#access-revoke-all) | `dome gateway access revoke-all ` |
| [Quota list](#quota-list) | `dome gateway quota list [gateway]` |
| [Quota set](#quota-set) | `dome gateway quota set --limit ` |
| [Quota update](#quota-update) | `dome gateway quota update [flags]` |
| [Quota remove](#quota-remove) | `dome gateway quota rm ` |
***
## List
`dome gateway list`
List Gateways in the active workspace: name, default marker, ID, state, and canonical endpoint path (`/gateways/`). Alias: `ls`.
The endpoint column shows one path per Gateway — the single URL every client points at. The Dome SDK and Anthropic clients use it as-is; MCP clients append `/mcp`; OpenAI-compatible clients append `/v1`. Refer to [Endpoint shape](/connect/gateways#build-the-runtime-endpoint).
## Get
`dome gateway get `
Show a Gateway's members — tools, tool sources (connections), LLM pools, and direct model connections — plus its canonical endpoint path (`/gateways/`), state, default marker, and grant settings.
## Create
`dome gateway create `
Create a Gateway. Starts active with empty membership; attach resources with the membership commands or `--gateway` at resource create.
| Flag | Type | Required | Default | Description |
| --------------- | ------ | -------- | ------- | -------------------------- |
| `--description` | string | No | — | Human-readable description |
```bash theme={"system"}
dome gateway create prod-tools --description "Production MCP tools for the ops agent"
```
## Update
`dome gateway update `
Rename or edit the description. Toggle state with [`enable`](#enable) / [`disable`](#disable).
| Flag | Type | Required | Default | Description |
| --------------- | ------ | -------- | ------- | ---------------- |
| `--name` | string | No | — | New Gateway name |
| `--description` | string | No | — | New description |
## Enable
`dome gateway enable `
Re-enable a disabled Gateway. Membership and grants are preserved.
## Disable
`dome gateway disable `
Disable a Gateway. Its endpoint fails closed until re-enabled.
## Set default
`dome gateway set-default `
Mark a Gateway as the workspace default — the pre-checked (but overridable) Gateway in the dashboard's tool, pool, and model create dialogs. A suggestion only; it enforces no membership and grants no access. Setting a new default clears the previous one. A disabled default is never pre-selected.
## Delete
`dome gateway delete `
Delete a Gateway. Its memberships are removed, but the underlying tools, pools, and model connections are unchanged. Aliases: `rm`, `remove`.
Callers pointed at this Gateway's `/gateways//…` endpoint will fail closed after deletion. Repoint them at another Gateway first.
***
## Tools add
`dome gateway tools add `
Add a single MCP tool to a Gateway. `` is the observed tool's ID from [`dome tool catalog list`](/cli/connect/tools#catalog-list). To include every tool from a connection — with newly discovered tools joining automatically — use [`tool-sources add`](#tool-sources-add) instead.
## Tools remove
`dome gateway tools remove `
Remove a single MCP tool. Alias: `rm`.
## Tool-sources add
`dome gateway tool-sources add `
Add an MCP server connection as a tool source. The Gateway includes every tool observed on the connection; newly discovered tools propagate automatically.
## Tool-sources remove
`dome gateway tool-sources remove `
Remove the tool source. Tools that joined only through this source stop being included. Alias: `rm`.
## Model-pools add
`dome gateway model-pools add `
Add an LLM pool. The Gateway exposes the pool's models at its `/gateways//v1` endpoint.
## Model-pools remove
`dome gateway model-pools remove `
Alias: `rm`.
## Models add
`dome gateway models add `
Add a direct (un-pooled) LLM model connection. The Gateway exposes the model without going through a pool — useful when a single provider serves one purpose.
## Models remove
`dome gateway models remove `
Alias: `rm`.
***
## Access list
`dome gateway access list `
List agents and whether each is currently granted access to the Gateway. Revoked agents are excluded — they cannot exchange their API key for a JWT, so they can never reach a gateway. Suspended agents remain in the list because suspension is reversible.
```bash theme={"system"}
dome gateway access list prod-tools --json
```
## Access grant
`dome gateway access grant `
Grant one agent access. Requires the agent-access permission set (`agent.register` + `rules.deploy`).
## Access revoke
`dome gateway access revoke `
Revoke one agent's access.
## Access grant-all
`dome gateway access grant-all `
Grant every current and future workspace agent access to this Gateway. Requires `rules.deploy` + `gateway.manage`.
## Access revoke-all
`dome gateway access revoke-all `
Clear the all-agents grant. Per-agent grants are unaffected.
***
## Quota list
`dome gateway quota list [gateway-name-or-id]`
List Gateway cost quotas (USD spend caps on a whole Gateway's aggregate LLM spend). Optionally filter to one Gateway. Alias: `ls`.
## Quota set
`dome gateway quota set --limit `
Create a USD spend cap that covers every LLM call routed through the Gateway's member pools and direct connections. Once window spend exceeds the cap, calls to the Gateway return HTTP `429`.
| Flag | Type | Required | Default | Description |
| ------------ | ------ | -------- | --------- | ---------------------------------------------- |
| `--limit` | string | Yes | — | Spend cap in US dollars, e.g. `500` or `12.50` |
| `--window` | string | No | `monthly` | Reset window: `daily` or `monthly` |
| `--name` | string | No | — | Human-readable quota label |
| `--disabled` | bool | No | `false` | Create in a disabled state |
```bash theme={"system"}
dome gateway quota set prod-tools --limit 500 --window monthly --name "prod-monthly"
```
## Quota update
`dome gateway quota update [flags]`
Update a Gateway quota's name, limit, window, or enabled state. The Gateway subject is immutable; create a new quota to cap a different Gateway.
| Flag | Type | Description |
| ----------- | ------ | -------------------------------------- |
| `--name` | string | New label |
| `--limit` | string | New spend cap in US dollars |
| `--window` | string | New reset window: `daily` or `monthly` |
| `--enabled` | bool | Enable or disable enforcement |
## Quota remove
`dome gateway quota rm `
Remove a Gateway cost quota. Aliases: `remove`, `delete`. Refuses IDs of non-Gateway quotas — use [`dome model quota rm`](/cli/connect/models#quota-remove) for those.
# dome model
Source: https://docs.domesystems.ai/cli/connect/models
Manage LLM model connections and routing pools
`dome model` registers LLM upstreams the gateway proxies — Anthropic, OpenAI, Azure OpenAI, Google, Bedrock, hosted OpenAI-compatible vendors (Groq, Mistral, Together, Fireworks, DeepSeek, xAI, Perplexity, Cohere, OpenRouter, Cerebras, NVIDIA, DeepInfra, SambaNova, AI21, Databricks), and self-hosted endpoints — and groups them into routing pools that fan out across providers with priority, weighting, and failover.
| Command | |
| ----------------------------------------- | ------------------------------------------------------------- |
| [List](#list) | `dome model list [workspace-id-or-slug]` |
| [Get](#get) | `dome model get ` |
| [Add](#add) | `dome model add ` |
| [Update](#update) | `dome model update ` |
| [Remove](#remove) | `dome model rm ` |
| [OAuth connect](#oauth-connect) | `dome model oauth-connect ` |
| [OAuth disconnect](#oauth-disconnect) | `dome model oauth-disconnect ` |
| [Pool create](#pool-create) | `dome model pool create ` |
| [Pool list](#pool-list) | `dome model pool list [workspace-id-or-slug]` |
| [Pool get](#pool-get) | `dome model pool get ` |
| [Pool update](#pool-update) | `dome model pool update ` |
| [Pool set default](#pool-set-default) | `dome model pool set-default ` |
| [Pool move](#pool-move) | `dome model pool move --before \| --after ` |
| [Pool remove](#pool-remove) | `dome model pool rm ` |
| [Pool gateways](#pool-gateways) | `dome model pool gateways list\|add\|remove [gateway]` |
| [Pool member add](#pool-member-add) | `dome model pool member add ` |
| [Pool member list](#pool-member-list) | `dome model pool member list ` |
| [Pool member update](#pool-member-update) | `dome model pool member update ` |
| [Pool member remove](#pool-member-remove) | `dome model pool member rm ` |
| [Quota list](#quota-list) | `dome model quota list` |
| [Quota set](#quota-set) | `dome model quota set --subject … --limit ` |
| [Quota remove](#quota-remove) | `dome model quota rm ` |
***
## List
`dome model list [workspace-id-or-slug]`
List LLM models in the workspace. Aliases: `ls`.
## Get
`dome model get `
Show details for one model, including provider config and Cedar attributes.
## Add
`dome model add `
Register an LLM model upstream. The shared API key, when supplied, is stored under the provider's managed auth header — `Authorization: Bearer …` for OpenAI, Bedrock, and OpenAI-compatible hosted vendors; `x-api-key` for Anthropic; `api-key` for Azure OpenAI; `x-goog-api-key` for Google. When `--endpoint` is omitted, the CLI prefills the vendor's default base URL from the provider registry.
| Flag | Type | Required | Default | Description |
| ------------------------ | ------------------- | -------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--provider` | string | Yes | — | `openai`, `anthropic`, `google`, `bedrock`, `azure_openai`, `mistral`, `groq`, `together`, `fireworks`, `deepseek`, `xai`, `perplexity`, `cohere`, `openrouter`, `cerebras`, `nvidia`, `deepinfra`, `sambanova`, `ai21`, `databricks`, `openai_compatible`, `custom`. Refer to [Supported providers](/reference/resources/models#providers) reference. |
| `--model` | string | No | — | Model id (e.g. `gpt-4o-mini`, `claude-3-5-sonnet-20241022`) |
| `--endpoint` | string | No | registry default | Provider endpoint URL. Required for `azure_openai`, `bedrock`, `databricks`, `openai_compatible`, and `custom`. |
| `--auth-method` | string | No | `api-key` | `none`, `api-key`, `oauth` |
| `--credential-type` | string | No | `shared` | `none`, `shared`, `per-user` |
| `--api-key` | string | No | — | API key (use with `--auth-method=api-key --credential-type=shared`) |
| `--provider-config` | JSON | No | — | Full `provider_config` as JSON; merges with `--model`/`--endpoint` |
| `--attributes` | JSON | No | — | Cedar attributes as JSON object |
| `--filter-window-bytes` | uint32 | No | `0` | Outbound filter window in bytes for this connection. `0` inherits the workspace floor; the engine takes the max of workspace, connection, and per-request. |
| `--filter-window-tokens` | uint32 | No | `0` | Outbound filter window in tokens for this connection. `0` inherits the workspace floor. |
| `--gateway` | string (repeatable) | No | — | Attach directly to the named [Gateway](/connect/gateways) (name or ID). Without it the model is unreachable until attached. |
```bash title="Anthropic shared API key" theme={"system"}
dome model add claude-sonnet \
--provider anthropic \
--model claude-3-5-sonnet-20241022 \
--api-key "$ANTHROPIC_API_KEY"
```
```bash title="Groq (endpoint prefilled from registry)" theme={"system"}
dome model add fast-groq \
--provider groq \
--model llama-3.3-70b-versatile \
--api-key "$GROQ_API_KEY"
```
```bash title="Azure OpenAI" theme={"system"}
dome model add gpt-4o \
--provider azure_openai \
--model gpt-4o \
--endpoint https://my-resource.openai.azure.com \
--api-key "$AZURE_OPENAI_KEY" \
--provider-config '{"api_version":"2024-08-01-preview","deployment":"gpt-4o-prod"}'
```
## Update
`dome model update `
Update a model. Only provided flags change. Provider is immutable post-create — switch by adding a new connection.
| Flag | Type | Description |
| ------------------------ | ------ | ---------------------------------------------------------------------------------------- |
| `--name` | string | New connection name |
| `--model` | string | New model id |
| `--endpoint` | string | New endpoint URL |
| `--auth-method` | string | New auth method |
| `--credential-type` | string | New credential scope |
| `--api-key` | string | Replace the shared API key |
| `--provider-config` | JSON | Replace `provider_config` wholesale |
| `--attributes` | JSON | Replace Cedar attributes (pass `'{}'` to clear) |
| `--filter-window-bytes` | uint32 | Per-connection outbound filter window in bytes. `0` clears back to the workspace floor. |
| `--filter-window-tokens` | uint32 | Per-connection outbound filter window in tokens. `0` clears back to the workspace floor. |
## Remove
`dome model rm `
Remove an LLM model. Aliases: `remove`, `delete`.
## OAuth connect
`dome model oauth-connect `
Begin the shared-OAuth admin consent flow for a model configured with `--auth-method=oauth --credential-type=shared`: Anthropic OAuth, Azure AAD/Entra service principal, Google Workload Identity for Vertex. Prints a one-shot URL valid for \~10 minutes. Open it in a browser to complete consent — Dome stores the tokens on the callback.
Per-user OAuth models do not use this command; consent is gateway-triggered on each end user's first call.
## OAuth disconnect
`dome model oauth-disconnect `
Revoke shared OAuth credentials. The OAuth client configuration is preserved, so a subsequent `oauth-connect` reuses the same client. Idempotent.
***
## Pool create
`dome model pool create `
Create a logical pool that fans out across one or more model connections.
| Flag | Type | Default | Description |
| -------------------- | ------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--description` | string | — | Pool description |
| `--match-when` | JSON | — | Predicate selecting this pool by request shape (e.g. `'{"prompt_tokens":{"gt":100000}}'`). Refer to [match\_when predicates](/reference/resources/model-pools#pool-resolution) reference. |
| `--default` | bool | `false` | Mark as workspace default (or use [`set-default`](#pool-set-default) later) |
| `--cache-ttl-secs` | int32 | `0` | Exact-match cache TTL (`0` disables) |
| `--cache-scope` | string | `workspace` | `workspace` or `caller` |
| `--routing-strategy` | string | `priority_weighted` | `priority_weighted`, `round_robin`, `least_loaded`. Refer to [Routing strategies](/reference/resources/model-pools#routing-strategies) reference. |
| `--strategy-scope` | string | `workspace` | Scope of stateful routing counters: `workspace` or `caller`. Ignored by `priority_weighted`. |
| `--failover-max` | string | `all` | Failover ceiling. `all` walks every member; integer `N` gives primary + N retries (`0` disables failover). |
| `--gateway` | string (repeatable) | — | Attach to the named [Gateway](/connect/gateways) (name or ID). Without it the pool is unreachable until attached. |
```bash title="Pool with two providers and weighted distribution" theme={"system"}
dome model pool create default --failover-max 2
dome model pool member add default claude-sonnet --priority 0 --weight 3
dome model pool member add default gpt-4o --priority 0 --weight 1
dome model pool member add default claude-haiku --priority 1
dome model pool set-default default
```
## Pool list
`dome model pool list [workspace-id-or-slug]`
List pools. Aliases: `ls`.
## Pool get
`dome model pool get `
Show pool config and its members.
## Pool update
`dome model pool update `
Update a pool. Only provided flags change. Pass `--match-when '{}'` to clear the match predicate.
| Flag | Type | Description |
| -------------------- | ------ | ------------------------------------------------------------------------------- |
| `--name` | string | Rename the pool |
| `--description` | string | New description |
| `--match-when` | JSON | Replace match predicate (pass `'{}'` to clear) |
| `--cache-ttl-secs` | int32 | New cache TTL (`0` disables) |
| `--cache-scope` | string | New cache scope |
| `--routing-strategy` | string | `priority_weighted`, `round_robin`, or `least_loaded` |
| `--strategy-scope` | string | `workspace` or `caller` |
| `--failover-max` | string | `all` (walk every member) or non-negative integer `N`. Omit to leave unchanged. |
## Pool set default
`dome model pool set-default `
Mark this pool as the workspace default. Replaces any prior default.
## Pool move
`dome model pool move --before ` or `--after `
Reposition a pool in its workspace's `match_when` evaluation order. Pools with non-empty predicates evaluate in ascending `sort_key`; the first match wins. Refer to [Pool order](/reference/resources/model-pools#pool-resolution) reference.
| Flag | Type | Description |
| ---------- | ------ | ------------------------------------------------------------ |
| `--before` | string | Anchor pool name; the moved pool lands immediately before it |
| `--after` | string | Anchor pool name; the moved pool lands immediately after it |
Exactly one of `--before` or `--after` is required.
## Pool remove
`dome model pool rm `
Remove a pool. Aliases: `remove`, `delete`.
## Pool gateways
`dome model pool gateways [gateway-name-or-id]`
Manage the pool's membership in [Gateways](/connect/gateways) from the pool side. Mirrors [`dome gateway model-pools`](/cli/connect/gateway#model-pools-add).
* `list ` — Gateways this pool belongs to. Alias: `ls`.
* `add ` — expose the pool's models at the Gateway's `/gateways//v1` endpoint.
* `remove ` — detach. Alias: `rm`.
***
## Pool member add
`dome model pool member add `
Add a model to a pool. Failover walks ascending priority; within a bucket, requests distribute by weight.
| Flag | Type | Default | Description |
| ------------ | ----- | ------- | -------------------------------------------------- |
| `--priority` | int32 | `0` | Priority (`0` = primary; failover walks ascending) |
| `--weight` | int32 | `1` | Weight within the priority bucket |
| `--enabled` | bool | `true` | Whether the member is included in routing |
## Pool member list
`dome model pool member list `
List members of a pool with priority, weight, and enabled state. Aliases: `ls`.
## Pool member update
`dome model pool member update `
Update a member's priority, weight, or enabled flag.
| Flag | Type | Description |
| ------------ | ----- | ---------------- |
| `--priority` | int32 | New priority |
| `--weight` | int32 | New weight |
| `--enabled` | bool | New enabled flag |
## Pool member remove
`dome model pool member rm `
Remove a member from a pool. Aliases: `remove`, `delete`.
***
## Quota list
`dome model quota list`
List LLM cost quotas in the workspace with their subject, USD limit, window, and enabled state. Aliases: `ls`. Refer to [Cost quotas](/govern/quotas#set-a-quota) for what each subject covers.
## Quota set
`dome model quota set --subject --limit `
Create a USD spend cap. The `--subject` flag decides what the cap covers; the gateway enforces it in-memory and either spills routing (per-model budgets) or rejects with 429 (total caps).
| Flag | Type | Required | Default | Description |
| -------------- | ------ | ----------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--subject` | string | Yes | — | `workspace`, `agent`, `act-as`, `pool`, `model`, or `gateway` |
| `--limit` | string | Yes | — | Cap in US dollars (e.g. `500` or `12.50`) |
| `--window` | string | No | `monthly` | Reset window: `daily` or `monthly` |
| `--name` | string | No | — | Optional human-readable label |
| `--model` | string | Conditional | — | Model connection name (`--subject model`) |
| `--pool` | string | Conditional | — | Pool name (`--subject pool`, or to scope a model quota to one pool) |
| `--agent` | string | Conditional | — | Agent id (`--subject agent`) |
| `--act-as` | string | Conditional | — | Verified end-user OIDC subject (`--subject act-as`) |
| `--gateway` | string | Conditional | — | Gateway name or id (`--subject gateway`). [`dome gateway quota set`](/cli/connect/gateway#quota-set) is the Gateway-first spelling of the same cap. |
| `--per-caller` | bool | No | `false` | Apply the limit independently to each agent and verified end user (`--subject model` only) |
| `--disabled` | bool | No | `false` | Create disabled; no enforcement until enabled |
```bash title="Workspace-wide monthly cap" theme={"system"}
dome model quota set --subject workspace --limit 5000 --window monthly
```
```bash title="Pool spill-over budget for one model" theme={"system"}
# Caps claude-sonnet spend inside the production pool at $1000/month.
# When exhausted, the pool spills to the next member.
dome model quota set \
--subject model --model claude-sonnet --pool production \
--limit 1000 --window monthly
```
```bash title="Per-caller daily cap" theme={"system"}
dome model quota set \
--subject model --model gpt-4o --per-caller \
--limit 25 --window daily
```
## Quota remove
`dome model quota rm `
Remove a quota by id (from `dome model quota list`). Aliases: `remove`, `delete`.
# dome tool
Source: https://docs.domesystems.ai/cli/connect/tools
Manage MCP server connections the gateway proxies for agents
`dome tool` registers upstream MCP servers (the "tools" an agent reaches through Dome) and manages their auth, outbound headers, and field classifications. To list the capabilities each agent currently sees, use [`dome agents list`](/cli/connect/agents#list) instead.
| Command | |
| --------------------------------------- | ------------------------------------------------------------- |
| [List](#list) | `dome tool list [workspace-id-or-slug]` |
| [Get](#get) | `dome tool get [workspace-id-or-slug]` |
| [Add](#add) | `dome tool add [workspace-id-or-slug]` |
| [Update](#update) | `dome tool update [workspace-id-or-slug]` |
| [Remove](#remove) | `dome tool remove [workspace-id-or-slug]` |
| [OAuth connect](#oauth-connect) | `dome tool oauth-connect [workspace-id-or-slug]` |
| [OAuth disconnect](#oauth-disconnect) | `dome tool oauth-disconnect [workspace-id-or-slug]` |
| [Gateways](#gateways) | `dome tool gateways list\|add\|remove [gateway]` |
| [Header list](#header-list) | `dome tool header list ` |
| [Header add](#header-add) | `dome tool header add ` |
| [Header remove](#header-remove) | `dome tool header remove ` |
| [Catalog list](#catalog-list) | `dome tool catalog list [workspace-id-or-slug]` |
| [Catalog sync](#catalog-sync) | `dome tool catalog sync [workspace-id-or-slug]` |
| [Catalog block](#catalog-block) | `dome tool catalog block ` |
| [Catalog deprecate](#catalog-deprecate) | `dome tool catalog deprecate ` |
| [Catalog restore](#catalog-restore) | `dome tool catalog restore ` |
***
## List
`dome tool list [workspace-id-or-slug]`
List MCP server connections. Aliases: `ls`.
## Get
`dome tool get [workspace-id-or-slug]`
Show details for one tool connection.
## Add
`dome tool add [workspace-id-or-slug]`
Register a new MCP server.
| Flag | Type | Required | Default | Description |
| ----------------------------- | ----------------------------- | ---------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--name` | string | Yes | — | Tool name (unique within workspace) |
| `--url` | string | Streamable | — | URL (required for `streamable-http`) |
| `--command` | string | Stdio | — | Command to exec (required for `stdio`) |
| `--arg` | string (repeatable) | No | — | Command argument for `stdio` |
| `--protocol` | string | No | `streamable-http` | `streamable-http`, `stdio` |
| `--header-literal` | `Name=Value` (repeatable) | No | — | Literal outbound header |
| `--header-secret` | `Name=SecretKey` (repeatable) | No | — | Outbound header sourced from a stored secret |
| `--header-actas` | `Name` (repeatable) | No | — | Header that reinjects the verified `X-Dome-Act-As` |
| `--authorization` | string | No | — | `Authorization` HTTP header value. REQUIRED with `--auth-method=api-key --credential-type=shared`. The server auto-injects the managed `Authorization` header — do not declare it via `--header-secret`. |
| `--secret-value` | `KEY=VALUE` (repeatable) | No | — | Advanced: per-tool credential bundle entry for custom secret-source headers. The `Authorization` key is reserved — use `--authorization` instead. |
| `--auth-method` | string | No | `none` | `none`, `api-key`, `oauth` |
| `--credential-type` | string | No | — | `shared`, `per-user` |
| `--oauth-authorize-url` | string | No | — | OAuth: authorize endpoint |
| `--oauth-token-url` | string | No | — | OAuth: token endpoint |
| `--oauth-revoke-url` | string | No | — | OAuth: revocation endpoint |
| `--oauth-registration-url` | string | No | — | OAuth: RFC 7591 registration endpoint (for `client-origin=dcr`) |
| `--oauth-client-id` | string | No | — | OAuth: client ID (required when `client-origin=manual`) |
| `--oauth-client-secret` | string | No | — | OAuth: client secret |
| `--oauth-default-scope` | string (repeatable) | No | — | OAuth: default scope |
| `--oauth-client-origin` | string | No | — | OAuth: `dcr` or `manual` |
| `--oauth-token-endpoint-auth` | string | No | `auto` | OAuth: `auto`, `client_secret_basic`, `client_secret_post`. `auto` discovers the server's preferred method via RFC 8414 metadata. |
| `--field-classification` | `key=value` | No | — | Field sensitivity labels (e.g. `email=PII,phone=PII`) |
| `--write-tools` | string | No | — | Comma-separated list of tool names classified as write operations |
| `--gateway` | string (repeatable) | No | — | Attach as a tool source to the named [Gateway](/connect/gateways) (name or ID). Without it the connection is unreachable until attached. |
When `--auth-method=oauth --credential-type=shared`, `add` automatically prints the URL to start the admin consent flow. Open it in a browser to complete consent. If the flow can't start automatically, run [`oauth-connect`](#oauth-connect) afterwards.
```bash title="Shared OAuth tool (manual client)" theme={"system"}
dome tool add \
--name notion \
--url https://mcp.notion.com/mcp \
--auth-method oauth \
--credential-type shared \
--oauth-client-origin manual \
--oauth-authorize-url https://api.notion.com/v1/oauth/authorize \
--oauth-token-url https://api.notion.com/v1/oauth/token \
--oauth-client-id "$NOTION_CLIENT_ID" \
--oauth-client-secret "$NOTION_CLIENT_SECRET" \
--oauth-default-scope read_content \
--oauth-default-scope update_content
```
```bash title="Per-user OAuth tool (dynamic client registration)" theme={"system"}
dome tool add \
--name jira \
--url https://mcp.atlassian.com/v1/sse \
--auth-method oauth \
--credential-type per-user \
--oauth-client-origin dcr \
--oauth-authorize-url https://auth.atlassian.com/authorize \
--oauth-token-url https://auth.atlassian.com/oauth/token \
--oauth-registration-url https://auth.atlassian.com/oauth/clients
```
## Update
`dome tool update [workspace-id-or-slug]`
Update an MCP server connection. Only provided flags change. Switching `--auth-method` between `api-key` and `oauth` clears the previously stored credential bundle.
| Flag | Type | Description |
| ------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `--url` | string | New URL |
| `--command` | string | New command (stdio) |
| `--arg` | string (repeatable) | Replace command args |
| `--protocol` | string | `streamable-http`, `stdio` |
| `--header-literal` | `Name=Value` (repeatable) | Replace literal-header list |
| `--header-secret` | `Name=SecretKey` (repeatable) | Replace secret-header list |
| `--header-actas` | `Name` (repeatable) | Replace act-as header list |
| `--authorization` | string | New `Authorization` value. Use to rotate an `api-key`+`shared` tool's token. |
| `--secret-value` | `KEY=VALUE` (repeatable) | Advanced: replace per-tool credential bundle |
| `--auth-method` | string | `none`, `api-key`, `oauth` |
| `--credential-type` | string | `shared`, `per-user` |
| `--oauth-*` | various | OAuth client config overrides (same shape as `add`). Empty `--oauth-client-secret` keeps the existing secret. |
| `--field-classification` | `key=value` | Add or update field classifications |
| `--remove-field-classification` | string\[] | Remove field classifications by name |
| `--write-tools` | string | Comma-separated write-tools list (replaces current) |
## Remove
`dome tool remove [workspace-id-or-slug]`
Remove an MCP server connection.
## Gateways
`dome tool gateways [gateway-name-or-id]`
Manage the connection's tool-source membership in [Gateways](/connect/gateways) from the connection side. Mirrors [`dome gateway tool-sources`](/cli/connect/gateway#tool-sources-add).
* `list ` — Gateways this connection is a tool source of. Alias: `ls`.
* `add ` — attach as a tool source; every observed tool joins, and newly discovered tools propagate automatically.
* `remove ` — detach. Alias: `rm`.
```bash theme={"system"}
dome tool gateways add notion prod-tools
```
## OAuth connect
`dome tool oauth-connect [workspace-id-or-slug]`
Begin the shared-OAuth admin consent flow. Prints a one-shot URL valid for \~10 minutes. Open it in a browser to complete consent at the upstream's authorization server. After consent, Dome stores the tokens.
Only valid for `--auth-method=oauth --credential-type=shared` tools. Per-user OAuth tools trigger consent automatically on each end user's first call.
```bash theme={"system"}
dome tool oauth-connect notion
```
## OAuth disconnect
`dome tool oauth-disconnect [workspace-id-or-slug]`
Revoke shared OAuth credentials. The OAuth client configuration is preserved, so a subsequent `oauth-connect` reuses the same client. Idempotent.
```bash theme={"system"}
dome tool oauth-disconnect notion
```
## Header list
`dome tool header list [workspace-id-or-slug]`
List the outbound headers configured on a tool.
## Header add
`dome tool header add [workspace-id-or-slug]`
Append outbound headers to a tool without replacing the existing list. Combine `--header-literal`, `--header-secret`, and `--header-actas` flags (refer to [`add`](#add) for shapes).
## Header remove
`dome tool header remove [workspace-id-or-slug]`
Remove outbound headers by name from a tool.
## Catalog list
`dome tool catalog list [workspace-id-or-slug]`
List the persistent MCP tool catalog for a connection — the tools the gateway has observed on the upstream MCP server. The catalog survives gateway restarts and stays queryable without a live data plane.
| Flag | |
| ---------------- | -------------------------------------------------------------------------------------------------------------------- |
| `--with-schema` | Include input schema in the output (truncated). |
| `--seen-since` | Only include tools seen within this window (e.g. `30d`, `24h`). Pass `0` for all-time. Defaults to `720h` (30 days). |
| `--show-blocked` | Include blocked tools (hidden by default). |
```bash theme={"system"}
dome tool catalog list notion --seen-since 7d
```
## Catalog sync
`dome tool catalog sync [workspace-id-or-slug]`
Sync the persistent MCP tool catalog for a `per-user` connection by dispatching exactly one upstream `tools/list` against the calling admin's own per-user credential. Shared connections already pre-warm via the gateway's startup discovery and are rejected client-side.
Attach your per-user credential first through the normal magic-link flow (refer to [`oauth-connect`](#oauth-connect) or the per-user provisioning flow in the dashboard), then run this command. Sync works both before any agent traffic (pre-warm) and after (refresh). The result is recorded through the shared catalog observation path and is visible to `dome tool catalog list` immediately afterwards.
| Flag | |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--act-as-sub` | Workspace-verified act-as subject under which the admin attached the per-user credential. Defaults to the calling admin's email. Required when the workspace's act-as verifier does not use email as Sub (e.g. OIDC/HMAC verifiers issuing opaque subs, or `local-auth` which sets Sub to a user UUID). |
```bash theme={"system"}
dome tool catalog sync notion
```
Prints four counters: tools observed, inserted, updated schema, and updated last-seen. Requires the `gateway.manage` permission. Returns `FailedPrecondition` when no per-user credential exists at the resolved sub-hash — the error message names both remedies (attach the credential, or pass `--act-as-sub`).
## Catalog block
`dome tool catalog block `
Hide a discovered MCP tool from agents. The Gateway filters the tool out of `tools/list` and denies any `tools/call` against it. A block takes precedence over ordinary connection-level access. Blocks persist across re-observation.
| Flag | Type | Required | Description |
| ----------- | ------ | -------- | --------------------------------------------------------------------------------------------- |
| `--message` | string | No | Operator note shown alongside the tool in dashboards and CLI (e.g. `"dangerous mass-delete"`) |
Requires the `gateway.manage` permission. Blocked-call attempts emit a `tool.blocked_call_denied` audit event.
```bash theme={"system"}
dome tool catalog block notion delete_page --message "dangerous mass-delete; use archive_page"
```
## Catalog deprecate
`dome tool catalog deprecate `
Mark a tool as deprecated. The tool stays callable and visible to agents; the dashboard renders a warning chip and operators see the status in `dome tool catalog list`. Use when an upstream replaces a tool and you want to soft-signal callers without breaking them.
| Flag | Type | Required | Description |
| ----------- | ------ | -------- | ------------------------------------------- |
| `--message` | string | No | Operator note (e.g. `"use create_page_v2"`) |
Requires the `gateway.manage` permission.
```bash theme={"system"}
dome tool catalog deprecate notion create_page --message "use create_page_v2"
```
## Catalog restore
`dome tool catalog restore `
Return a tool to `active`, clearing any prior block or deprecation.
Requires the `gateway.manage` permission.
```bash theme={"system"}
dome tool catalog restore notion delete_page
```
`dome tool catalog list ` shows the current `STATUS` column for every observed tool. Blocked tools are hidden by default — pass `--show-blocked` to include them.
# dome quickstart
Source: https://docs.domesystems.ai/cli/developer/quickstart-cmd
Scaffold a new Dome-enabled project
##
`dome quickstart [name]`
Creates a new project directory with Dome SDK integration, starter rules, and configuration.
```bash theme={"system"}
dome quickstart my-agent-project
```
| Flag | Type | Default | Description |
| ------------------- | ------ | ------- | ---------------------------------- |
| `--language` | string | `go` | Project language (supported: `go`) |
| `--non-interactive` | bool | false | Skip confirmation prompts |
### Generated Files
| File | Description |
| -------------- | ------------------------------------- |
| `main.go` | Entry point with Dome SDK integration |
| `go.mod` | Go module definition |
| `dome.yaml` | Dome configuration |
| `.env.example` | Environment variable template |
| `Dockerfile` | Container build definition |
| `rules.cedar` | Starter authorization rules |
# dome sandbox
Source: https://docs.domesystems.ai/cli/developer/sandbox
Provision sandbox environments for development and testing
## Provision
`dome sandbox provision`
Provision a sandbox environment.
```bash theme={"system"}
# Create a sandbox workspace in the current tenant
dome sandbox provision --scope=workspace
# Create an isolated sandbox tenant with workspace and API key
dome sandbox provision --scope=tenant
```
| Flag | Type | Required | Description |
| ------------------ | ------ | -------- | --------------------------------------------------------- |
| `--scope` | string | Yes | Scope: `tenant` or `workspace` |
| `--tenant-name` | string | No | Sandbox tenant name suffix (auto-generated if omitted) |
| `--workspace-name` | string | No | Sandbox workspace name suffix (auto-generated if omitted) |
### Scope Options
* **`workspace`** — creates a sandbox workspace in the current tenant. Requires tenant admin, operator, or security role.
* **`tenant`** — creates an isolated sandbox tenant with a workspace and API key. Requires org admin or owner role.
# CLI Overview
Source: https://docs.domesystems.ai/cli/index
Install, authenticate, and navigate the Dome CLI
The `dome` CLI is the primary command-line interface for the Dome Platform.
## Installation
```bash title="macOS (Homebrew)" theme={"system"}
brew trust dome-systems/tap
brew install dome-systems/tap/dome
```
Homebrew 6 requires the `brew trust` line before it loads a third-party tap's formulae. Refer to [Install](/install) for the full walkthrough, including a direct-download alternative.
## Global Flags
All commands support these flags:
| Flag | Type | Description |
| ------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--context` | string | Use a specific context (overrides active context) |
| `--server` | string | Dome Platform server URL |
| `--activity` | string | Stable activity ID this run asserts. Every Connect RPC carries `X-Dome-Activity-Id` so audit events from the run share one [activity chain](/operate/audit#list-activity-chains). Overrides `DOME_ACTIVITY_ID`. |
| `--json` | bool | Output as JSON |
| `--quiet` | bool | Minimal output (IDs only) |
| `--no-color` | bool | Disable colored output |
## Environment Variables
| Variable | Description |
| ------------------ | --------------------------------------------------------------- |
| `DOME_API_KEY` | Sets the active context's token. Useful for CI and scripts. |
| `DOME_ACTIVITY_ID` | Default activity ID for the process. `--activity` overrides it. |
## Command Groups
### Connect
| Command | Description |
| --------------------------------- | ----------------------------------------------------- |
| [`agents`](/cli/connect/agents) | Manage agent registrations, lifecycle, and API keys |
| [`gateway`](/cli/connect/gateway) | Manage Gateways, membership, agent access, and quotas |
| [`tool`](/cli/connect/tools) | Manage MCP server connections the gateway proxies |
| [`model`](/cli/connect/models) | Manage LLM model connections and routing pools |
### Secure
| Command | Description |
| ---------------------------- | ------------------------------------------------------------ |
| [`rules`](/cli/secure/rules) | Deploy, validate, simulate, and rollback authorization rules |
### Operate
| Command | Description |
| ----------------------------------- | ------------------------------------------------------------------------ |
| [`audit`](/cli/operate/audit) | Query, stream, and export audit events |
| [`webhooks`](/cli/operate/webhooks) | Manage webhook subscriptions, delivery history, and the provider catalog |
| [`usage`](/cli/operate/usage) | Show LLM token usage and estimated cost for the active workspace |
### Settings
| Command | Description |
| ---------------------------------------------- | -------------------------------------------------------------- |
| [`tenants`](/cli/settings/tenants) | Create tenants under your active organization |
| [`workspace`](/cli/settings/workspace) | Manage workspaces, members, act-as, and verification providers |
| [`platform-keys`](/cli/settings/platform-keys) | Manage platform API keys |
| [`config`](/cli/settings/config) | Platform configuration |
### Developer
| Command | Description |
| --------------------------------------------- | ----------------------------------- |
| [`quickstart`](/cli/developer/quickstart-cmd) | Scaffold a new Dome-enabled project |
| [`sandbox`](/cli/developer/sandbox) | Provision sandbox environments |
### Session
| Command | Description |
| --------------------------------- | --------------------------------------------------- |
| [`auth`](/cli/session/auth) | Authentication management |
| [`context`](/cli/session/context) | Manage CLI contexts (org/tenant/workspace sessions) |
### Standalone
| Command | Description |
| ------------------------------------ | ------------------------ |
| [`mcp`](/cli/standalone/mcp) | MCP server for AI agents |
| [`version`](/cli/standalone/version) | Show CLI version |
## Next steps
Authenticate first, then scaffold — or drive the same jobs from MCP:
* [Install](/install) to authenticate and select a workspace
* [Quickstart](/quickstart) to scaffold and verify governed traffic
* [MCP](/reference/mcp) when you prefer tool-based access from an assistant
* [API](/api) for the management and data-plane HTTP surfaces
# dome audit
Source: https://docs.domesystems.ai/cli/operate/audit
Query, stream, get, export audit events, and list activity chains
| Command | |
| ----------------- | -------------------------------- |
| [Query](#query) | `dome audit query` |
| [Stream](#stream) | `dome audit stream` |
| [Get](#get) | `dome audit get [event-id]` |
| [Export](#export) | `dome audit export` |
| [Chains](#chains) | `dome audit chains` |
| [Chain](#chain) | `dome audit chain [activity-id]` |
All commands scope the read to the active workspace (from `dome config`), so the server checks the workspace-level `audit.view` permission. Switch workspaces with `dome workspace use ` before running the command. Tenant- or org-scoped API keys with no workspace selected fall back to the tenant-level `audit.view`.
***
## Query
`dome audit query`
Query audit events with optional filters.
| Flag | Type | Description |
| ------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `--types` | string\[] | Filter by event types |
| `--classes` | string\[] | `governing`, `state_change`, `security`, `audit_access` |
| `--results` | string\[] | `attempted`, `succeeded`, `denied`, `failed`, `filtered`, `noop`, `permitted` |
| `--agent-id` | string | Filter by agent ID |
| `--agent-ids` | string\[] | Filter by agent IDs |
| `--primary-resource-id` | string | Filter by primary resource ID |
| `--primary-resource-kind` | string | Filter by primary resource kind |
| `--trace-id` | string | Filter by trace ID — events for one request |
| `--activity-id` | string | Filter by activity chain ID. Refer to [Activity chains](/reference/events#correlation) reference. |
| `--operation-id` | string | Filter by operation ID |
| `--parent-event-id` | string | Filter by parent event ID |
| `--actor-kind` | string | Filter by actor kind |
| `--actor-id` | string | Filter by actor ID |
| `--producer-service` | string | Filter by producer service |
| `--producer-gateway-id` | string | Filter by producer Gateway ID |
| `--request-surface` | string | Filter by request surface |
| `--caller-surface` | string | Filter by caller application surface |
| `--payload-filter` | string\[] | `event.type:field` or `event.type:field=value` (repeatable). Refer to [Payload filters](/reference/events#payload-filters) reference. |
| `--since` | string | Start time (RFC3339) |
| `--until` | string | End time (RFC3339) |
| `--limit` | int32 | Maximum results (default: 50) |
| `--page-token` | string | Cursor from a previous query |
| `--compact` | bool | Bounded investigation rows; use `audit get` for full payload |
## Stream
`dome audit stream`
Stream audit events in real-time via SSE. Accepts the same filters as [`query`](#query) except `--limit` and `--compact`.
| Flag | Type | Description |
| ------------------------- | --------- | ------------------------------------ |
| `--types` | string\[] | Filter by event types |
| `--classes` | string\[] | Filter by event classes |
| `--results` | string\[] | Filter by event results |
| `--agent-id` | string | Filter by agent ID |
| `--agent-ids` | string\[] | Filter by agent IDs |
| `--primary-resource-id` | string | Filter by primary resource ID |
| `--primary-resource-kind` | string | Filter by primary resource kind |
| `--trace-id` | string | Filter by trace ID |
| `--activity-id` | string | Follow one activity chain live |
| `--operation-id` | string | Filter by operation ID |
| `--parent-event-id` | string | Filter by parent event ID |
| `--actor-kind` | string | Filter by actor kind |
| `--actor-id` | string | Filter by actor ID |
| `--producer-service` | string | Filter by producer service |
| `--producer-gateway-id` | string | Filter by producer Gateway ID |
| `--request-surface` | string | Filter by request surface |
| `--caller-surface` | string | Filter by caller application surface |
| `--payload-filter` | string\[] | Payload filter (repeatable) |
| `--since` | string | Start time (RFC3339) |
| `--until` | string | End time (RFC3339) |
| `--page-token` | string | Cursor from a previous stream |
## Get
`dome audit get [event-id]`
Get a single audit event by ID.
Enum values — event class, result, actor kind, surface — render as short tokens (`governing`, `denied`, `gateway_mcp`) in both the table and `--format json` output, and the filter flags accept those same tokens. Refer to [Enum rendering](/reference/events#enum-rendering) reference.
## Export
`dome audit export`
Export audit events in JSON-lines, JSON, OCSF, or CEF format. Pick the format your downstream pipeline expects:
| Format | Output |
| ----------------- | ------------------------------------------------------------------ |
| `jsonl` (default) | One JSON object per line (NDJSON). |
| `json` | Single pretty-printed JSON array. |
| `ocsf` | OCSF v1.1.0 JSON array for Splunk, Sentinel, or Chronicle. |
| `cef` | Common Event Format lines for ArcSight, QRadar, or generic syslog. |
Accepts the same filters as [`query`](#query), plus:
| Flag | Type | Description |
| ---------- | ------ | -------------------------------------------------------- |
| `--limit` | int32 | Maximum results (default: 1000) |
| `--format` | string | `jsonl`, `json`, `csv`, `ocsf`, `cef` (default: `jsonl`) |
```bash theme={"system"}
# Export the last 24 hours as OCSF for a SIEM
dome audit export \
--since 2026-05-26T00:00:00Z \
--format ocsf > audit.ocsf.json
```
## Chains
`dome audit chains`
List activity chains in the active workspace. A chain is the set of audit events sharing one `activity_id` — a session, an LLM turn, a conversation thread, or a scripted run — computed at read time by grouping on `activity_id` within the workspace.
A chain is listed when **any** of its events matches the filter. Per-chain counts always reflect the full chain. Drill into one chain's events with [`dome audit chain `](#chain). Refer to [Activity chains](/reference/events#correlation) reference for the model and trust labels.
| Flag | Type | Description |
| -------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------- |
| `--types` | string\[] | Chain contains an event of these types |
| `--classes` | string\[] | Chain contains an event of these classes (`governing`, `state_change`, `security`, `audit_access`) |
| `--results` | string\[] | Chain contains an event with these results (`attempted`, `succeeded`, `denied`, `failed`, `filtered`, `noop`, `permitted`) |
| `--agent-id` | string | Chain contains an event for this agent |
| `--agent-ids` | string\[] | Chain contains an event for these agents |
| `--actor-kind` | string | Chain contains an event with this actor kind |
| `--actor-id` | string | Chain contains an event with this actor ID |
| `--producer-service` | string | Chain contains an event from this producer service |
| `--request-surface` | string | Chain contains an event from this request surface |
| `--since` | string | Start time (RFC3339) |
| `--until` | string | End time (RFC3339) |
| `--limit` | int32 | Maximum chains (default: 50) |
| `--page-token` | string | Cursor from a previous chains query |
Per-event identity filters (`--trace-id`, `--operation-id`, `--parent-event-id`) and payload filters identify a single event, not a chain, and are not offered here.
```bash theme={"system"}
# Recent chains in the active workspace
dome audit chains --limit 20
# Chains that contain a denied governing event in the last day
dome audit chains \
--classes governing \
--results denied \
--since 2026-06-05T00:00:00Z
```
Each row reports the chain's `activity_id`, event count, last activity timestamp, outcome breakdown, trust label (`server-owned`, `caller-asserted`, or mixed — refer to [Activity trust](/reference/events#correlation) reference), and distinct event-type count.
## Chain
`dome audit chain [activity-id]`
Show one activity chain's events in order. A drill-in into `audit query` filtered by `activity_id`. Accepts the same per-event filters as `audit query` to narrow the chain's events further.
| Flag | Type | Description |
| ------------------ | --------- | ----------------------------------------------------------------------------- |
| `--types` | string\[] | Filter by event types |
| `--classes` | string\[] | Filter by event classes |
| `--results` | string\[] | Filter by event results |
| `--agent-id` | string | Filter by agent ID |
| `--actor-kind` | string | Filter by actor kind |
| `--actor-id` | string | Filter by actor ID |
| `--payload-filter` | string\[] | Payload filter as `event.type:field` or `event.type:field=value` (repeatable) |
| `--since` | string | Start time (RFC3339) |
| `--until` | string | End time (RFC3339) |
| `--limit` | int32 | Maximum events (default: 200) |
| `--page-token` | string | Cursor from a previous query |
```bash theme={"system"}
# Every event in one chain
dome audit chain case-12345
# Only the denied events in that chain
dome audit chain case-12345 --results denied
```
## Emit events into a chain
Set `--activity` (or `DOME_ACTIVITY_ID`) on the root command to assert a stable activity ID. Every Connect RPC the run makes carries `X-Dome-Activity-Id`, so the audit events all share one `activity_id` and form one chain.
```bash theme={"system"}
# One run, many commands, one chain.
export DOME_ACTIVITY_ID="case-12345"
dome agents register --name worker
dome rules deploy ./rules
dome audit query --limit 5
# Inspect the chain you just emitted.
dome audit chains --since 2026-06-05T00:00:00Z
dome audit chain case-12345
```
`--activity` overrides `DOME_ACTIVITY_ID`. The ID is opaque to Dome — pick whatever maps to your unit of work. The header is first-party only and is never forwarded to third-party LLM or MCP backends.
The `--activity` emit flag (root command) and the `--activity-id` filter flag (audit reads) are distinct: one stamps events, the other selects them.
# dome usage
Source: https://docs.domesystems.ai/cli/operate/usage
Show LLM token usage and estimated cost for the active workspace
Print LLM token consumption and a per-class cost estimate for the active workspace. Use it to spot-check spend, build budget alerts in scripts, or confirm token attribution matches what the dashboard and `dome_usage` MCP tool show.
The estimated cost is a blended cross-model rate intended for trend-watching, not a billable figure. Refer to [Token Usage and Cost](/operate/observe#token-usage-and-cost) for the full token-class breakdown and pricing model.
## Usage
`dome usage`
Reads `GET /api/v1/metrics/summary` for the active workspace over the last 24 hours and renders the totals.
| Flag | Type | Description |
| -------- | ---- | ---------------------------- |
| `--json` | bool | Output as JSON for scripting |
**Permission:** workspace `audit.view`
**Prerequisites:** active workspace selected (`dome context use ` or `dome workspace use `).
```bash theme={"system"}
dome usage
```
Output (table):
```
LLM token usage (last 24h)
Input tokens 412000
Cache read tokens 1820000
Cache write tokens 88000
Output tokens 64000
Reasoning tokens 12000
Total tokens 2396000
Estimated cost $3.4521 (per-class estimate, not billable)
```
Output (`--json`):
```json theme={"system"}
{
"llm_input_tokens": 412000,
"llm_cache_read_tokens": 1820000,
"llm_cache_write_tokens": 88000,
"llm_output_tokens": 64000,
"llm_reasoning_tokens": 12000,
"llm_total_tokens": 2396000,
"estimated_cost_usd": 3.4521
}
```
Pipe into `jq` to build budget guards:
```bash theme={"system"}
# Fail if estimated 24h spend crosses $10
cost=$(dome usage --json | jq '.estimated_cost_usd')
awk "BEGIN { exit !($cost > 10) }" && echo "over budget" >&2
```
For per-agent, per-key, per-identity, or per-model attribution, see the [REST query surface](/operate/observe#token-usage-and-cost) — the dashboard and the [`dome_usage`](/reference/mcp/audit#audit-usage) MCP tool consume the same endpoints.
# dome webhooks
Source: https://docs.domesystems.ai/cli/operate/webhooks
Manage webhook subscriptions, delivery history, and the provider catalog
| Command | |
| ----------------------------------------------------------- | -------------------------------------------------------- |
| [Subscriptions list](#subscriptions-list) | `dome webhooks subscriptions list` |
| [Subscriptions get](#subscriptions-get) | `dome webhooks subscriptions get ` |
| [Subscriptions create](#subscriptions-create) | `dome webhooks subscriptions create …` |
| [Subscriptions update](#subscriptions-update) | `dome webhooks subscriptions update ` |
| [Subscriptions disable](#subscriptions-disable) | `dome webhooks subscriptions disable ` |
| [Subscriptions rotate-secret](#subscriptions-rotate-secret) | `dome webhooks subscriptions rotate-secret ` |
| [Subscriptions test](#subscriptions-test) | `dome webhooks subscriptions test ` |
| [Subscriptions delete](#subscriptions-delete) | `dome webhooks subscriptions delete ` |
| [Deliveries list](#deliveries-list) | `dome webhooks deliveries list` |
| [Deliveries get](#deliveries-get) | `dome webhooks deliveries get ` |
| [Deliveries replay](#deliveries-replay) | `dome webhooks deliveries replay ` |
| [Deliveries replay-failed](#deliveries-replay-failed) | `dome webhooks deliveries replay-failed --since ` |
| [Deliveries cancel](#deliveries-cancel) | `dome webhooks deliveries cancel ` |
| [Providers list](#providers-list) | `dome webhooks providers list` |
| [Providers get](#providers-get) | `dome webhooks providers get ` |
`dome webhooks` also answers to `dome events`. Group aliases: `subscriptions` = `sub`, `deliveries` = `del`, every `list` = `ls`, `delete` = `rm`.
All commands scope to the active workspace (from `dome context`).
### Permissions
| Permission | Commands |
| ----------------- | ---------------------------------------------------------------------------------- |
| `eventing.view` | All `list` and `get` commands |
| `eventing.manage` | Subscription create, update, disable, rotate-secret, test, delete; delivery cancel |
| `eventing.replay` | `deliveries replay`, `deliveries replay-failed` |
Workspace `admin` and `operator` roles hold all three. `security`, `developer`, and `viewer` hold `eventing.view`.
***
## Subscriptions list
`dome webhooks subscriptions list`
List every subscription in the active workspace with its delivery endpoint, event types, and active state.
## Subscriptions get
`dome webhooks subscriptions get `
Show a subscription's delivery endpoint, provider, event types, filters, and active state. Name matching is case-insensitive.
## Subscriptions create
`dome webhooks subscriptions create (--url | --provider ) --event-type `
Create a subscription and its delivery destination atomically. A failed request leaves neither record behind.
```
Subscription "alerts" created (id: …)
Signing secret (shown once, key key_…): whsec_…
```
The signing secret prints **once** — capture it before the terminal closes. It is only recoverable via `rotate-secret`. Providers that authenticate with a credential in the body (PagerDuty) send unsigned deliveries and return no secret.
| Flag | Type | Description |
| ------------------ | --------- | ------------------------------------------------------------------------------------------- |
| `--url` | string | Custom HTTPS endpoint URL. Exactly one of `--url` or `--provider`. |
| `--provider` | string | Provider key from `providers list`. |
| `--setting` | string\[] | Provider setting `key=value` (repeatable). Non-secret. |
| `--credential` | string\[] | Provider credential `key=value` (repeatable). Stored write-only. |
| `--event-type` | string\[] | Event type to subscribe to (repeatable, required). |
| `--filter` | string\[] | Filter predicate (repeatable). Refer to [filter grammar](#filter-grammar). |
| `--content-format` | string | Custom URL only: `object` (default) or `array` (one-element JSON array). |
| `--header-literal` | string\[] | Custom header `Name=Value` (repeatable). Custom URL only. |
| `--header-secret` | string\[] | Custom header `Name=Value` stored write-only, masked on read (repeatable). Custom URL only. |
### Filter grammar
| Form | Meaning |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `key=value` | Exact match. Repeat the same key for an OR set. |
| `key~=glob` | Glob pattern. `*` any run, `?` one char, `\` escapes. Matches the full value, case-sensitive. |
| `tool=conn/tool` | Sugar. Splits at the first `/` into `connection_name` + `tool_name` filters; each side globs when it contains `*` or `?`. |
Filter keys: `agent_name`, `connection_name` (resolved from IDs at delivery time), `agent_id`, `tool_name`, plus each event type's own filterable payload fields — browse them in the dashboard's **Event catalog** tab. An event delivers only if it satisfies every filter that applies to its type.
## Subscriptions update
`dome webhooks subscriptions update `
Update a subscription or its delivery destination. Unpassed flags leave the field untouched.
| Flag | Type | Description |
| ------------------- | --------- | ----------------------------------------------------------------------------- |
| `--name` | string | New display name. |
| `--event-type` | string\[] | Replace the full event-type set (repeatable). |
| `--filter` | string\[] | Replace the full filter set (repeatable). Excludes `--clear-filters`. |
| `--clear-filters` | bool | Remove every filter. |
| `--active` | bool | `--active=false` pauses fanout; `--active` resumes it. No backfill on resume. |
| `--url` | string | Replace the destination URL. |
| `--endpoint-active` | bool | Enable or disable the destination itself. |
| `--content-format` | string | `object` or `array`. Custom URL only. |
| `--header-literal` | string\[] | Upsert a literal header `Name=Value`. |
| `--header-secret` | string\[] | `Name=Value` rotates the secret; bare `Name` keeps the stored value. |
| `--remove-header` | string\[] | Remove a header by name. |
| `--clear-headers` | bool | Remove all custom headers. |
| `--setting` | string\[] | Replace the full provider settings set `key=value`. |
| `--credential` | string\[] | Merge a write-only provider credential `key=value`. |
## Subscriptions disable
`dome webhooks subscriptions disable `
Stop new fanout. Delivery history and pending retries remain queryable.
## Subscriptions rotate-secret
`dome webhooks subscriptions rotate-secret `
Rotate the destination's HMAC signing secret. Prints the new secret **once**:
```
New signing secret (shown once, key key_…): whsec_…
```
During the grace window the `webhook-signature` header carries a signature per active key, so a consumer verifying with either secret keeps working.
## Subscriptions test
`dome webhooks subscriptions test `
Send a fixed `eventing.test` event through the subscription's destination. Verifies signing, headers, and the destination's own routing end-to-end. Prints the queued delivery ID — inspect it with `deliveries get`.
## Subscriptions delete
`dome webhooks subscriptions delete `
Delete the subscription and cancel every pending delivery. Delivery history stays queryable.
***
## Deliveries list
`dome webhooks deliveries list`
Inspect deliveries by status, event type, subscription, or time window. Prints last attempt, status, event type, delivery ID, attempt count, and last error per row.
| Flag | Type | Description |
| ------------------- | ------ | ------------------------------------------------------------------------------------------------------------------- |
| `--subscription-id` | string | Narrow to one subscription ID. |
| `--destination-id` | string | Narrow to one destination ID. |
| `--event-type` | string | Narrow to one event type. |
| `--status` | string | One of `created`, `enqueued`, `delivering`, `retry_scheduled`, `succeeded`, `failed`, `canceled`, `expired`, `dlq`. |
| `--event-id` | string | Every delivery for one source event. |
| `--start` | string | RFC3339 start time. |
| `--end` | string | RFC3339 end time. |
| `--limit` | int | Page size. |
| `--page-token` | string | Cursor from a previous listing. |
## Deliveries get
`dome webhooks deliveries get `
Show a delivery with its status, timing, last HTTP status, and per-attempt history.
| Flag | Type | Description |
| -------- | ---- | ----------------------------------------------------------------------------------------------------------- |
| `--body` | bool | Include the delivered webhook body while retained — up to 30 days, or 24 hours after a successful delivery. |
## Deliveries replay
`dome webhooks deliveries replay `
Replay one delivery. Creates a **new** delivery from the retained body — fresh `webhook-id`, same `Dome-Event-Id` — and sends another request to the destination. Consumers that dedupe on `Dome-Event-Id` ignore the overlap.
## Deliveries replay-failed
`dome webhooks deliveries replay-failed --since `
Bulk-replay terminally-failed deliveries in a time window — the outage-recovery counterpart to `replay`. Safe to re-run: a delivery with a live or succeeded replay is not matched again, and canceled deliveries are never recovered.
| Flag | Type | Description |
| ---------------- | --------- | --------------------------------------------------------------------------------------------- |
| `--since` | string | Duration back from now (`24h`, `7d`) or RFC3339 timestamp. Required, within the last 30 days. |
| `--until` | string | RFC3339 upper bound. Defaults to now. |
| `--subscription` | string | Narrow to one subscription name or ID. |
| `--status` | string\[] | Statuses to recover — subset of `failed`, `expired`, `dlq`. Default all three. |
| `--max` | int | Deliveries per run, up to 500. Repeat the command to continue. |
Prints `matched · replayed · skipped (body expired) · failed`.
## Deliveries cancel
`dome webhooks deliveries cancel `
Cancel a delivery's pending retries. No further request is sent to the destination.
***
## Providers list
`dome webhooks providers list`
List every off-the-shelf provider with its setting and credential fields, recommended event bundle, and authentication style — Standard Webhooks signature or credential-in-body.
## Providers get
`dome webhooks providers get `
Show a provider's setup instructions, documentation link, and `--setting` / `--credential` fields. Run before `subscriptions create --provider`.
# dome guards
Source: https://docs.domesystems.ai/cli/secure/guards
Author content-inspection Filters and assign them to model and MCP server connections
`dome guards` manages Guards — content-inspection definitions that redact, omit, or block governed traffic. A Filter is a workspace-scoped, versioned Guard bound to a connection's ordered chain per direction. Text Filters attach to model connections; JSON Filters attach to MCP server (tool) connections.
| Command | |
| ------------------------------------------------------- | ------------------------------------------------------------ |
| [Filters list](#filters-list) | `dome guards filters list` |
| [Filters get](#filters-get) | `dome guards filters get ` |
| [Filters versions](#filters-versions) | `dome guards filters versions ` |
| [Filters create](#filters-create) | `dome guards filters create ` |
| [Filters update](#filters-update) | `dome guards filters update ` |
| [Filters rollback](#filters-rollback) | `dome guards filters rollback --to-version ` |
| [Filters delete](#filters-delete) | `dome guards filters delete ` |
| [Model guards filters list](#model-guards-filters-list) | `dome model guards filters list ` |
| [Model guards filters set](#model-guards-filters-set) | `dome model guards filters set ` |
| [Tool guards filters list](#tool-guards-filters-list) | `dome tool guards filters list ` |
| [Tool guards filters set](#tool-guards-filters-set) | `dome tool guards filters set ` |
Editing a Filter deploys a new active version. Assigned connections pick it up on the next gateway sync — history is preserved and can be rolled back to.
## Filter kinds
A Filter's kind is structural and immutable at create time.
| Kind | Assignable to | Component | Actions |
| ------ | ----------------------------- | -------------------------------------------------------------------------- | ------------------------- |
| `text` | Model connections | Ordered text-content matchers (substring, SSN, credit card, phone, digits) | `redact`, `block` |
| `json` | MCP server (tool) connections | Ordered JSON field-actions keyed by field name | `redact`, `omit`, `block` |
Both kinds enforce **fail-closed**: a Filter whose stored config fails to decode blocks that `(connection, direction)` until the config is fixed. The gateway never relays unfiltered traffic.
***
## Filters list
`dome guards filters list`
List the workspace's Filters, showing each one's active version and a compact config summary (e.g. `redact[substring:"foo", ssn]; block[substring:"bar"]` or `omit[ssn, dob]; redact[email]`).
## Filters get
`dome guards filters get `
Show a single Filter's active version and config.
| Arg | Type | Required | Description |
| ------------ | ------ | -------- | -------------------------------------- |
| `name-or-id` | string | Yes | Filter name (workspace-scoped) or UUID |
## Filters versions
`dome guards filters versions `
List the Filter's version history (newest first). Rollback-produced versions cite the source version id.
## Filters create
`dome guards filters create `
Create a Filter — its first active version.
```bash theme={"system"}
# Text Filter: redact SSNs and a substring, then block on another substring
dome guards filters create pii-redact \
--description "Redact PII in model responses" \
--redact-ssn \
--redact-substring "internal-only" \
--block-substring "TOP-SECRET"
# JSON Filter: omit and redact fields in tool arguments/results (via --config-from)
dome guards filters create tool-scrub --config-from ./tool-scrub.json
```
| Flag | Type | Required | Default | Description |
| -------------------- | ------------------- | ------------------------------- | ------- | ----------------------------------------------------------------------------------------------------- |
| `--description` | string | No | — | One-line description |
| `--redact-substring` | string (repeatable) | Text only | — | Redact matches of this substring |
| `--block-substring` | string (repeatable) | Text only | — | Block the response on a substring match |
| `--redact-ssn` | bool | Text only | `false` | Redact US SSN patterns |
| `--block-ssn` | bool | Text only | `false` | Block the response on an SSN match |
| `--config-from` | path or `-` | For JSON, or full-fidelity text | — | Read a protojson `dome.guards.v1.FilterConfig` from a file or stdin. Overrides the convenience flags. |
The convenience flags build at most two components — a `redact` component and a `block` component, redact ordered first — and only produce text Filters. Use `--config-from` to author a JSON Filter or a multi-component text chain.
### JSON Filter config example
```json title="tool-scrub.json" theme={"system"}
{
"json": {
"components": [
{
"field_actions": [
{ "matcher": { "key": "ssn" }, "action": "FILTER_ACTION_OMIT" },
{ "matcher": { "key": "dob" }, "action": "FILTER_ACTION_OMIT" },
{ "matcher": { "key": "email" }, "action": "FILTER_ACTION_REDACT" },
{ "matcher": { "key": "card" }, "action": "FILTER_ACTION_BLOCK" }
]
}
]
}
}
```
`BLOCK` withholds the whole message. `OMIT` removes the key and value. `REDACT` rewrites the value with a redaction sentinel. When multiple actions target the same key, `BLOCK` > `OMIT` > `REDACT`.
## Filters update
`dome guards filters update `
Edit metadata in place, or deploy a new active version by passing any config flag. The old version is preserved in history and assigned connections follow the active version on the next gateway sync.
| Flag | Type | Description |
| --------------------------------------------------------------------------------------------- | ------ | -------------------------------------------- |
| `--name` | string | New name for the logical Filter |
| `--description` | string | New description |
| `--redact-substring` / `--block-substring` / `--redact-ssn` / `--block-ssn` / `--config-from` | — | Any config flag deploys a new active version |
Pass at least one of name, description, or a config flag.
## Filters rollback
`dome guards filters rollback --to-version `
Roll a Filter back to an earlier version. The target version's config is copied forward into a new active version — history is never mutated.
| Flag | Type | Required | Description |
| -------------- | ----- | -------- | ------------------------------ |
| `--to-version` | int32 | Yes | Version number to roll back to |
## Filters delete
`dome guards filters delete `
Hard-delete a Filter and its connection assignments. Corrupt Filters can still be addressed by UUID even when their config fails to render.
***
## Model guards filters list
`dome model guards filters list `
List the text Filters assigned to a model connection, in chain order, grouped by direction.
| Arg | Type | Required | Description |
| ------------ | ------ | -------- | --------------------- |
| `connection` | string | Yes | Model connection name |
## Model guards filters set
`dome model guards filters set `
Replace the entire ordered Filter chain for one direction on a model connection. Only `text`-kind Filters may be assigned.
```bash theme={"system"}
# Order matters — filters run in the given order
dome model guards filters set claude-prod \
--direction response \
--filters pii-redact,secrets-block
# Clear a chain
dome model guards filters set claude-prod --direction request --filters ""
```
| Flag | Type | Required | Description |
| ------------- | -------------------- | -------- | ------------------------------------------------------------------------------ |
| `--direction` | string | Yes | `response` (completions the agent receives) or `request` (the outbound prompt) |
| `--filters` | comma-separated list | Yes | Ordered Filter names or UUIDs; empty clears the chain |
`request` runs before dispatch to the upstream provider — a match can redact the prompt or block the call. `response` runs on the streamed completion; multi-chunk patterns are inspected inside the [LLM outbound filter window](/govern/guards#configure-the-streaming-window).
***
## Tool guards filters list
`dome tool guards filters list `
List the JSON Filters assigned to an MCP server (tool) connection, in chain order, grouped by direction.
| Arg | Type | Required | Description |
| ------------ | ------ | -------- | -------------------------- |
| `connection` | string | Yes | MCP server connection name |
## Tool guards filters set
`dome tool guards filters set `
Replace the entire ordered Filter chain for one direction on a tool connection. Only `json`-kind Filters may be assigned.
```bash theme={"system"}
# Scrub PII from tool arguments before they leave, and again from results
dome tool guards filters set github-mcp \
--direction request \
--filters tool-scrub
dome tool guards filters set github-mcp \
--direction response \
--filters tool-scrub
```
| Flag | Type | Required | Description |
| ------------- | -------------------- | -------- | -------------------------------------------------------------------------------------------- |
| `--direction` | string | Yes | `response` (tool result returned to the agent) or `request` (tool arguments before dispatch) |
| `--filters` | comma-separated list | Yes | Ordered Filter names or UUIDs; empty clears the chain |
`request` filters run over tool arguments **before** the call reaches the upstream MCP server — matched fields are redacted or omitted, or the whole call is blocked. `response` filters run over the tool result before the agent sees it.
# dome rules
Source: https://docs.domesystems.ai/cli/secure/rules
Deploy, validate, simulate, and rollback authorization rules
| Command | |
| --------------------- | --------------------------------- |
| [Apply](#apply) | `dome rules apply [files...]` |
| [List](#list) | `dome rules list` |
| [Show](#show) | `dome rules show` |
| [Validate](#validate) | `dome rules validate [files...]` |
| [Rollback](#rollback) | `dome rules rollback ` |
| [Generate](#generate) | `dome rules generate` |
| [Simulate](#simulate) | `dome rules simulate` |
***
## Apply
`dome rules apply [files...]`
Deploy a rule bundle from one or more Cedar files.
```bash theme={"system"}
dome rules apply rules.cedar [flags]
```
| Flag | Type | Description |
| --------------- | ------ | -------------------------------------------------------------------------------------------------- |
| `--agent` | string | Agent name or ID — deploy rules scoped to this agent |
| `--name` | string | Friendly name for the rule bundle |
| `--court-scope` | string | Directional [Court-review marker](/govern/judges): `none` (default), `reduce`, `expand`, or `both` |
After a successful deploy, `apply` prints advisory `warning:` lines to
stderr for any `Dome::MCPTool` reference that does not match a tool in
the target workspace's persisted MCP tool catalog (typo, rename, or a
tool not yet observed). Warnings never block the deploy.
## List
`dome rules list`
List rule bundle history.
| Flag | Type | Description |
| --------- | ------ | -------------------------------------------------- |
| `--agent` | string | Agent name or ID — list rules scoped to this agent |
| `--limit` | int | Maximum results (default: 20) |
## Show
`dome rules show`
Show effective rules across the full scope hierarchy.
| Flag | Type | Description |
| --------- | ------ | -------------------------------------------------- |
| `--agent` | string | Agent name or ID — show rules scoped to this agent |
## Validate
`dome rules validate [files...]`
Validate Cedar rule files without deploying. Returns errors and prints catalog warnings (unknown tools or connections) to stderr. Pass `--agent` to run catalog checks against an agent's scope — without it, only syntax and semantic validation runs.
```bash theme={"system"}
dome rules validate rules.cedar [flags]
```
| Flag | Type | Description |
| --------- | ------ | ---------------------------------------------------------- |
| `--agent` | string | Agent name or ID — validate rules against this agent scope |
## Rollback
`dome rules rollback `
Rollback to a previous rule bundle. The bundle UUID (from `dome rules list`) encodes the scope — no extra flags needed.
## Generate
`dome rules generate`
Generate starter Cedar authorization rules.
| Flag | Type | Description |
| -------------- | ------ | ---------------------------------------- |
| `--from-tools` | bool | Generate rules based on registered tools |
| `--output` | string | Write rules to file (default: stdout) |
## Simulate
`dome rules simulate`
Simulate an authorization decision against active rules.
| Flag | Type | Required | Description |
| ----------------- | --------- | -------- | ------------------------------------------------------------ |
| `--agent` | string | Yes | Agent ID or name |
| `--action` | string | Yes | Action to evaluate (e.g., `mcp:call`) |
| `--resource` | string | Yes | Resource identifier |
| `--resource-type` | string | No | `mcp_tool`, `llm_model`, or `resource` (default: `mcp_tool`) |
| `--eval-context` | key=value | No | Evaluation context key-value pairs (repeatable) |
| `--actas-sub` | string | No | Act-as subject identifier |
| `--actas-email` | string | No | Act-as email |
| `--actas-roles` | string | No | Act-as roles (comma-separated) |
| `--actas-groups` | string | No | Act-as groups (comma-separated) |
# dome auth
Source: https://docs.domesystems.ai/cli/session/auth
Authentication management
| Command | |
| ----------------- | ------------------ |
| [Login](#login) | `dome auth login` |
| [Logout](#logout) | `dome auth logout` |
| [Status](#status) | `dome auth status` |
***
## Login
`dome auth login`
Authenticate with the Dome Platform.
Opens your default browser for authentication. After login, an identity session is created and all available org/tenant contexts are synced.
```bash theme={"system"}
dome auth login
```
| Flag | Type | Description |
| --------- | ------ | -------------------------------------- |
| `--token` | string | API token for CI/headless environments |
## Logout
`dome auth logout`
Sign out and remove stored credentials.
## Status
`dome auth status`
Show authentication status including active context, server, org, tenant, and role.
# dome context
Source: https://docs.domesystems.ai/cli/session/context
Manage CLI contexts (org/tenant/workspace sessions)
Contexts represent authenticated sessions scoped to a specific org, tenant, and workspace.
| Command | |
| ------------------- | ------------------------------------------- |
| [List](#list) | `dome context list` |
| [Current](#current) | `dome context current` |
| [Use](#use) | `dome context use [name]` |
| [Sync](#sync) | `dome context sync` |
| [Rename](#rename) | `dome context rename ` |
| [Delete](#delete) | `dome context delete ` |
| [Alias](#alias) | `dome context alias ` |
***
## List
`dome context list`
List all contexts in org/tenant/workspace hierarchy. Aliases: `ls`.
## Current
`dome context current`
Show the active context name.
```text theme={"system"}
prod/acme/backend
```
With `--format json`, the response includes the context name, level, server, and available organization, tenant, and workspace names. Use `dome gateway list` or `dome gateway get` for complete Gateway URLs.
## Use
`dome context use [name]`
Switch the active context by name, alias, or shorthand.
```bash theme={"system"}
# By exact name
dome context use "prod/acme/backend"
# By alias
dome context use backend
# By shorthand (workspace name)
dome context use backend
# By shorthand (tenant/workspace)
dome context use acme/backend
# By shorthand (org/tenant/workspace)
dome context use prod/acme/backend
```
If the shorthand is ambiguous, an error lists the matching contexts.
| Flag | Type | Description |
| --------------------- | ---- | ------------------------------ |
| `--interactive`, `-i` | bool | Interactively select a context |
## Sync
`dome context sync`
Refresh contexts from server memberships. Fetches all org/tenant memberships and creates or updates local contexts with scoped session tokens.
| Flag | Type | Description |
| ---------- | ------ | ---------------------------------------------------------- |
| `--server` | string | Sync only this server (default: all authenticated servers) |
## Rename
`dome context rename `
Rename a context.
## Delete
`dome context delete `
Delete a context.
## Alias
`dome context alias `
Set or remove an alias for a context. Pass two args (context-name and alias) to set an alias. With `--remove`, pass a single arg (the alias to remove).
| Flag | Type | Description |
| ---------- | ---- | -------------------------------------------------------- |
| `--remove` | bool | Remove the alias (pass the alias as the single argument) |
# dome config
Source: https://docs.domesystems.ai/cli/settings/config
Platform configuration
## Get
`dome config get [key]`
Get a configuration value by key.
```bash theme={"system"}
dome config get audit.retention_days
dome config get registry.staleness_window
```
# dome platform-keys
Source: https://docs.domesystems.ai/cli/settings/platform-keys
Manage platform API keys for users and CI
Platform API keys provide programmatic access for users and CI pipelines. For agent authentication keys, use `dome agents create-key`.
| Command | |
| --------------------------- | ---------------------------------------- |
| [List](#list) | `dome platform-keys list` |
| [Create](#create) | `dome platform-keys create` |
| [Revoke](#revoke) | `dome platform-keys revoke [name-or-id]` |
| [Permissions](#permissions) | `dome platform-keys permissions` |
***
## List
`dome platform-keys list`
List platform API keys for the current workspace.
## Create
`dome platform-keys create`
Create a new platform API key.
| Flag | Type | Required | Description |
| --------------- | --------- | ----------- | ---------------------------------------------------------------------------------------------------------------- |
| `--name` | string | Yes | Key name |
| `--permissions` | string\[] | Conditional | Permissions to grant. Required in non-interactive mode; in an interactive terminal a picker is shown if omitted. |
| `--expires-at` | string | No | Expiration time (RFC3339) |
The interactive picker fetches the grantable permissions for your role at the current scope. Use [`dome platform-keys permissions`](#permissions) to discover the same list non-interactively.
## Revoke
`dome platform-keys revoke [name-or-id]`
Revoke a platform API key by name or ID.
## Permissions
`dome platform-keys permissions`
List the permissions you can grant to a new platform API key at the current context's scope. The output is exactly what `dome platform-keys create --permissions` will accept for your role; the server re-validates on submit.
Use this for CI scripts that need to know valid `--permissions` values, or to confirm what `create` would offer in its interactive picker.
The scope follows your active context: a workspace context returns workspace permissions, a tenant context adds tenant permissions, and an org context adds org permissions on top.
```bash theme={"system"}
dome platform-keys permissions
```
```bash theme={"system"}
dome platform-keys permissions --format json
```
Workspace admins do not see tenant-only permissions such as `agent.delete` or `agentkey.manage` in this list. Switch to a tenant or org context (or have a tenant admin run the command) to grant them.
# dome tenants
Source: https://docs.domesystems.ai/cli/settings/tenants
List, inspect, and create tenants under your active organization
Manage tenants in your organization. List, get, and create are gated on the org-level `tenant.manage` permission (held by org `admin` or `owner`); `get` additionally admits any caller whose active session is scoped to the requested tenant.
## List
`dome tenants list`
List tenants under your active organization.
| Flag | Type | Required | Description |
| ---------- | ------ | -------- | ------------------------------------------------------ |
| `--org-id` | string | No | Target org UUID. Defaults to the active context's org. |
**Permission:** Org-level `tenant.manage` (held by org `owner` or `admin`).
```bash title="List tenants in the active org" theme={"system"}
dome tenants list
```
```bash title="Target a specific org" theme={"system"}
dome tenants list --org-id 7d2c…
```
Output is a table of `ID`, `NAME`, `PLAN`, and `CREATED`. Pass `--format json` for the raw response.
## Get
`dome tenants get `
Get a single tenant by id. The caller is admitted if either (a) their active session is scoped to the requested tenant, or (b) they hold org `admin` or `owner` on the requested tenant's org.
| Argument / Flag | Type | Required | Description |
| --------------- | ------ | -------- | ------------------------------------------------------ |
| `` | string | Yes | Tenant UUID |
| `--org-id` | string | No | Target org UUID. Defaults to the active context's org. |
**Permission:** Tenant-scoped session for the requested tenant **or** org-level `tenant.manage` on the requested tenant's org.
```bash title="Get a tenant in the active org" theme={"system"}
dome tenants get 5b1e…
```
```bash title="Get a tenant from a specific org" theme={"system"}
dome tenants get 5b1e… --org-id 7d2c…
```
Output is a key/value table including ID, name, plan, org id, default gateway, and created timestamp. Pass `--format json` for the raw response.
## Create
`dome tenants create`
Create a new tenant under your active organization. The caller becomes the initial tenant admin.
| Flag | Type | Required | Description |
| ---------- | ------ | -------- | ----------------------------------------------------------------------- |
| `--name` | string | Yes | Tenant display name |
| `--plan` | string | No | Tenant plan: `essential` (default), `managed`, `enterprise`, `complete` |
| `--org-id` | string | No | Target org UUID. Defaults to the active context's org. |
**Permission:** Org-level `tenant.manage` on the org named in `--org-id` (held by org `owner` or `admin`). The permission check runs against the request's target org, not your active context — a caller authorized on org X cannot create a tenant in org Y by overriding `--org-id`.
```bash title="Create a tenant under the active org" theme={"system"}
dome tenants create --name acme-prod --plan managed
```
```bash title="Target a specific org" theme={"system"}
dome tenants create --name acme-staging --org-id 7d2c…
```
`dome tenants create` works directly after `dome auth login` — no prior `dome use` is required. As long as `--org-id` (or the default active org) names an org you hold `tenant.manage` on, the request succeeds.
Creating a new organization is operator-only. Contact Dome to provision a new org.
# dome workspace
Source: https://docs.domesystems.ai/cli/settings/workspace
Manage workspaces, members, act-as enforcement, policy freshness, and verification providers
## Workspace Lifecycle
### List
`dome workspace list`
List workspaces in the active tenant. Aliases: `ls`.
### Create
`dome workspace create`
Create a new workspace.
| Flag | Type | Required | Description |
| -------- | ------ | -------- | ---------------------- |
| `--name` | string | Yes | Workspace display name |
### Get
`dome workspace get `
Get workspace details. The output includes the configured `Freshness Window` — how long the gateway may serve cached policy for the workspace before failing closed.
### Delete
`dome workspace delete `
Delete a workspace permanently.
## Members
### Members list
`dome workspace members list [workspace-id-or-slug]`
List workspace memberships.
### Members set
`dome workspace members set [workspace-id-or-slug]`
Set a user's role in a workspace.
| Flag | Type | Required | Description |
| -------- | ------ | -------- | ----------------------------------------------- |
| `--user` | string | Yes | User email |
| `--role` | string | Yes | Role: `admin`, `operator`, `security`, `viewer` |
### Members remove
`dome workspace members remove [workspace-id-or-slug]`
Remove a user's workspace membership. If the user has active API keys, an interactive picker prompts you to select which to revoke; pass `--revoke-all-keys` or `--revoke-keys` to skip the prompt.
| Flag | Type | Required | Description |
| ------------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------- |
| `--user` | string | Yes | User email |
| `--revoke-keys` | string\[] | No | Comma-separated API key IDs to revoke (skips interactive prompt). Mutually exclusive with `--revoke-all-keys`. |
| `--revoke-all-keys` | bool | No | Revoke all API keys created by the user (skips interactive prompt). Mutually exclusive with `--revoke-keys`. |
## Act-As Enforcement
### Actas get
`dome workspace actas get [workspace-id-or-slug]`
Get the act-as enforcement policy.
### Actas update
`dome workspace actas update [workspace-id-or-slug]`
Update the act-as enforcement policy.
| Flag | Type | Description |
| ------------------- | --------- | --------------------------------------------------- |
| `--required` | bool | Require act-as header on all requests |
| `--allowed-methods` | string\[] | Allowed verification methods (e.g., `oidc`, `hmac`) |
## Policy Freshness Window
Each workspace has a configurable freshness window that bounds how long the gateway may serve cached authorization policy for that workspace before failing closed. Default is 90 seconds; allowed range is 30–86400 seconds. Enforcement is per-workspace — one workspace failing closed does not affect others.
### `dome workspace set-freshness-window [workspace-id-or-slug]`
Set the freshness window (in seconds) for a workspace.
| Argument | Type | Required | Description |
| ------------------------ | ------ | -------- | --------------------------------------------------- |
| `` | uint | Yes | Freshness window in seconds (30–86400) |
| `[workspace-id-or-slug]` | string | No | Target workspace (defaults to the active workspace) |
Once the window elapses, the gateway returns `access_denied` for every request in that workspace and emits a `authorization.staleness_rejected` audit event until the workspace's policy is fresh again.
## Verification Providers
### Verification-providers list
`dome workspace verification-providers list [workspace-id-or-slug]`
List verification providers.
### Verification-providers create
`dome workspace verification-providers create [workspace-id-or-slug]`
Create a verification provider.
| Flag | Type | Required | Description |
| ---------------------- | ------ | ----------- | ----------------------------------------------- |
| `--name` | string | Yes | Provider name |
| `--method` | string | Yes | Verification method: `oidc` or `hmac` |
| `--oidc-discovery-url` | string | Conditional | OIDC issuer discovery URL (required for `oidc`) |
| `--hmac-secret` | string | Conditional | HMAC shared secret (required for `hmac`) |
### Verification-providers delete
`dome workspace verification-providers delete [workspace-id-or-slug]`
Delete a verification provider.
# dome mcp
Source: https://docs.domesystems.ai/cli/standalone/mcp
MCP server for AI agents
## Serve
`dome mcp serve`
Start an MCP server on stdio. Exposes Dome Platform operations as tools for MCP clients like Claude.
Authentication is read from the active CLI context.
### Setup
```bash theme={"system"}
dome auth login
dome mcp serve
```
### Claude Integration
```bash theme={"system"}
claude mcp add dome -- dome mcp serve
```
Or add manually to your MCP config:
```json theme={"system"}
{
"mcpServers": {
"dome": {
"command": "dome",
"args": ["mcp", "serve"]
}
}
}
```
See the [MCP Server Reference](/reference/mcp) for the complete tool list organized by group.
# dome version
Source: https://docs.domesystems.ai/cli/standalone/version
Show CLI version information
## Version
`dome version`
Show the dome CLI version, commit, build time, Go version, and OS/architecture.
```bash theme={"system"}
dome version
```
| Flag | Type | Description |
| --------- | ---- | ------------------------- |
| `--check` | bool | Check for a newer version |
# Agent lifecycle
Source: https://docs.domesystems.ai/concepts/agents/agent-lifecycle
The four states an agent moves through, what triggers each transition, and what cascades
## High-level overview
The lifecycle is a directed graph with four states, two reversible transitions, and one terminal state. Provisioned and active agents can send traffic through the gateway. Suspended and revoked agents are rejected. Revocation is permanent. Suspension is reversible.
Moving an agent through its lifecycle looks like this:
1. An operator registers an agent.
2. The agent stays provisioned until its first gateway request, then becomes active automatically.
3. During an incident the operator suspends the agent (optionally cascading to active children).
4. After the window, reactivate restores traffic for that agent alone.
5. If the agent is decommissioned, revoke permanently disables it and every descendant.
Lifecycle state gates whether the agent identity can send traffic. That gate is independent of rotating keys or rewriting Rules.
![Agent lifecycle states: provisioned, active, suspended, revoked]()
### States
| State | Description | Can receive traffic? |
| --------------- | --------------------------------------------------- | -------------------- |
| **provisioned** | Created but never used. Waiting for first request. | Yes |
| **active** | Operational. Making requests and receiving traffic. | Yes |
| **suspended** | Temporarily disabled by an operator. | No |
| **revoked** | Permanently decommissioned. Terminal. | No |
### Transitions
#### Provisioned to Active
Happens **automatically** on first traffic. When a provisioned agent sends its first request through the gateway, the platform records the timestamp (`LastSeenAt`) and transitions the agent to active. No operator action required.
#### Active to Suspended
Triggered by an operator via `dome agents suspend`. Suspension is reversible. Use it for maintenance windows, incident response, or temporary access revocation.
With `--cascade`, the platform also suspends all active child agents in the hierarchy. Without it, only the target agent is suspended.
#### Suspended to Active
Triggered by an operator via `dome agents reactivate`. The agent immediately resumes accepting traffic.
#### Any State to Revoked
Triggered by an operator via `dome agents revoke`. Revocation is **permanent** and **always cascades**. Every descendant in the hierarchy is revoked depth-first, regardless of their current state. There is no undo.
### Cascade semantics
Agents form hierarchies through the `parent_id` field (max depth: 10). Cascade behavior differs between suspend and revoke:
| Operation | Cascade behavior | Reversible? |
| ----------- | --------------------------------------------------------- | ----------- |
| **Suspend** | Optional (`--cascade`). Suspends active descendants only. | Yes |
| **Revoke** | Always. Revokes all descendants depth-first, any state. | No |
The parent must belong to the same tenant as the child. Cross-tenant hierarchies are not permitted.
Hierarchy grants no access on its own. Each agent reaches only what you allow it. Refer to [Agents](/concepts/agents#lifecycle-and-hierarchy) concept and [Agents](/connect/agents#hierarchy).
### Heartbeat and staleness
The platform tracks `LastSeenAt` for every agent. It is updated on each request through the gateway. This timestamp serves two purposes:
* **Automatic activation.** Transitions provisioned agents to active on first traffic.
* **Staleness detection.** Operators can identify agents that have stopped communicating, though there is no automatic suspension on staleness.
## Next steps
With the agent lifecycle model in mind, continue with:
* [Agents](/concepts/agents) concept for how agents are identified and authenticated
* [Agent Identity](/concepts/agents/identity) concept for credentials and act-as claims
* [Agents](/connect/agents) to suspend, reactivate, revoke, and manage hierarchy
* [Rules](/concepts/controls/rules) concept when authorization should also reference agent state
# Agent identity
Source: https://docs.domesystems.ai/concepts/agents/identity
How agents authenticate: API keys, token exchange, session tokens, and act-as claims
## High-level overview
Dome authenticates agents in layers. An API key is the long-lived secret. The Identity service exchanges it for a short-lived session token. Every API call, MCP invocation, and gateway request carries that token. Services verify it locally. When the agent acts for a person, an act-as claim on `X-Dome-Act-As` can carry verified end-user identity beside the agent.
Issuing credentials and authenticating looks like this:
1. An operator registers an agent and creates an API key.
2. The runtime calls `ExchangeToken` with that key, receives a JWT, and sends the JWT on each request.
3. Dome confirms the agent is active, reads claims from the token, and proceeds to Gateway and Rule checks.
4. If the call also carries a verified act-as header, Rules can test `principal.act_as` and audit records the end user next to the agent.
Every request authenticates the agent with a self-contained session token. End-user claims are optional verified context beside that agent.
![Identity flow: API Key → Token Exchange → Session Token → Authenticated Request]()
The gateway uses separate credentials for outbound backend calls. Follow the complete request path in [Architecture](/concepts/architecture).
The CLI handles token exchange automatically. Run `dome auth login` and the CLI manages key exchange, token refresh, and header injection.
### How authentication works
1. **API key issuance.** Register an agent and [create an API key](/connect/agents#create-key). The key is returned once. Store it immediately.
2. **Token exchange.** The agent sends the API key to the Identity service (`ExchangeToken` with `grant_type: api_key`). The service validates the key, confirms the agent is active, and returns a short-lived JWT. Tune the lifetime per-workspace via [`identity.token_ttl`](/manage/settings#token-lifetime) (default `10m`, range `1m`–`24h`).
3. **Session token.** The JWT carries the agent's identity for all subsequent requests. There is no round-trip to the Identity service on every call. The token is self-contained and verified locally.
4. **Authenticated requests.** Every API call, MCP invocation, and gateway request carries the session token. Services extract identity without additional lookups.
### Session token
The session token is a JWT (HMAC-SHA256) carrying:
| Claim | Description |
| -------------- | -------------------------------------------------- |
| `sub` | Agent UUID |
| `jti` | Unique token ID |
| `iss` | `dome` |
| `aud` | `["dome"]` |
| `iat` / `exp` | Issued-at and expiration timestamps |
| `agent_id` | Agent UUID |
| `tenant_id` | Tenant UUID. Scopes all operations to this tenant. |
| `workspace_id` | Workspace UUID (when workspace context is set) |
| `capabilities` | Agent capability strings |
| `api_key_id` | The specific API key that minted this token |
The token is self-contained: any service can verify it locally using the signing key without calling the Identity service. Expiration is enforced on every request.
### Act-as identity
Act-as identity identifies the end user represented by a [delegated agent](/concepts/identity-patterns#delegated-identity). Attach that user's claims with the `X-Dome-Act-As` header. Configure providers and the workspace floor on [Delegated agents](/connect/agents/delegated).
#### What it carries
Verified claims land on `principal.act_as` (`sub`, `email`, `roles`, `groups`, and custom `claims`). Claim list for setup: [Delegated agents](/connect/agents/delegated#identity-claims). Attribute types for policy: [Rules](/reference/controls/rules#principal-attributes).
#### How it's verified
Act-as claims are untrusted by default. Verification (`oidc`, `hmac`, `bound`, or `none` for development only) ensures the agent is not fabricating user identities. Method catalog: [Delegated agents](/connect/agents/delegated#verification-methods).
Configure verification at the [workspace level](/connect/agents/delegated#require-verified-identity) as a baseline, or per-agent for tighter control. Workspace enforcement is a floor. Agents can add stricter verification but cannot weaken it.
#### Act-as in authorization rules
Once verified, act-as claims are available in Cedar rules:
```cedar title="rules.cedar" theme={"system"}
// Allow tool access only when the end-user has the analyst role
permit(
principal,
action == Dome::Action::"mcp:call",
resource
) when {
principal.act_as.roles.contains("analyst")
};
```
Full `principal.act_as` attribute notes are on the [Rules](/reference/controls/rules) reference.
## Next steps
With that authentication and act-as model in mind, continue with:
* [Agents](/concepts/agents) concept for how agents are identified and authenticated
* [Identity Patterns](/concepts/identity-patterns) concept for standing vs delegated design
* [Agents](/connect/agents) to create keys and manage agents
* [Delegated agents](/connect/agents/delegated) for act-as providers, methods, claims, and enforcement
* [Architecture](/concepts/architecture) concept for where identity sits on the request path
# Agents
Source: https://docs.domesystems.ai/concepts/agents/index
Why Dome uses agent identity as the principal for auth, authorization, and audit
## High-level overview
Registering an agent creates a durable identity in a workspace. That identity is separate from credentials and from access. An API key or short-lived token lets the runtime authenticate as the agent. Allowed resources, Gateway access grants, and Rules decide what requests Dome permits. You can rotate a key without changing permissions, or change permissions without issuing a new key.
Registering an agent and calling through Dome looks like this:
1. An operator registers `data-pipeline`, allows a Gateway and the tools behind it, and creates an API key.
2. The runtime exchanges the key for a session token and calls through the Gateway.
3. Dome authenticates the agent, checks the access grant and resource membership, evaluates Rules (and Guards and Quotas on the content path), and records the outcome against that agent identity.
4. Suspending the agent later stops traffic for that identity without deleting the record.
One agent identity covers authentication, authorization, and audit. Credentials and access stay separate.
### Identity is not permission
An agent credential identifies the caller. It does not contain the agent's permissions and is not bound to a specific Gateway. The same agent credentials can use multiple Gateways when the agent has an access grant to each one.
Three separate checks must allow a request:
| Check | Asks |
| ---------------- | --------------------------------------------------- |
| **Access grant** | May this agent use the Gateway? |
| **Membership** | Is this resource in the Gateway? |
| **Rule** | May this agent perform this action on the resource? |
Allowed resources on the agent record are shorthand for creating Rules in the agent's rule bundle. Changing them needs `rules.deploy` in addition to permission to edit the agent. When the shorthand cannot express a condition, author Rules directly. Refer to [Rules](/concepts/controls/rules) concept and [Agents](/connect/agents#allowed-resources).
### Credentials
Agents authenticate with an API key or a short-lived agent token minted from a key. Keys are issued once and cannot be retrieved again. Rotate or revoke a key to cut off that credential. Session tokens carry the agent UUID, tenant and workspace context, capabilities, and the API key id that minted them. Details are on the [Agent Identity](/concepts/agents/identity) concept.
### Capabilities
Capabilities are permission strings declared on an agent and carried in its token, such as `mcp:call` or `llm:invoke`. They describe classes of action the agent may attempt. Cedar Rules then authorize each specific request. Dome derives many capabilities from allowed resources. You set a capability yourself when a Rule tests a string Dome would not derive.
### Delegated identity
An agent can act for a person rather than only for itself (**delegated identity**). When it presents an act-as claim, Dome verifies the claim before authorizing the request, and the audit trail records the end user alongside the agent. Workspace and per-agent settings control whether a claim is required and which verified identities the agent may present. Refer to [Delegated agents](/connect/agents/delegated) and [Identity Patterns](/concepts/identity-patterns) concept.
### Lifecycle and hierarchy
Every agent has a lifecycle state: provisioned, active, suspended, or revoked. Provisioned and active agents can send traffic. Suspended and revoked agents are rejected. Revocation is permanent and always cascades to descendants. An agent can have a parent in the same tenant (max depth 10). Hierarchy grants no access on its own. Refer to [Agent Lifecycle](/concepts/agents/agent-lifecycle) concept.
## Next steps
With the agent identity model in mind, continue with:
* [Architecture](/concepts/architecture#agents) concept for where agents sit among components and controls
* [Agent Identity](/concepts/agents/identity) concept for API keys, tokens, and act-as claims
* [Agent Lifecycle](/concepts/agents/agent-lifecycle) concept for states and transitions
* [Identity Patterns](/concepts/identity-patterns) concept for standing vs delegated design
* [Gateways](/concepts/gateways) concept for reachability after identity
* [Rules](/concepts/controls/rules) concept for what an agent may do once it reaches a resource
* [Agents](/connect/agents) to register, issue keys, and manage agents
# Authorization model
Source: https://docs.domesystems.ai/concepts/architecture/authorization-model
How Cedar rules evaluate permit and forbid against the assembled effective policy
## How a request is decided
Each request maps to one principal (`Dome::Agent`), one action (`Dome::Action`), and one resource (`Dome::MCPTool` or `Dome::LLMModel`). Conditions may also read request `context` and, when present, verified act-as claims on the principal.
```cedar title="examples.cedar" theme={"system"}
permit(
principal == Dome::Agent::"data-pipeline",
action == Dome::Action::"mcp:call",
resource == Dome::MCPTool::"database-query"
);
forbid(
principal,
action == Dome::Action::"mcp:call",
resource == Dome::MCPTool::"production-deploy"
) unless {
principal.capabilities.contains("production:deploy")
};
```
### Evaluation semantics
1. The evaluator checks every rule in the effective policy against the request.
2. If **any** `forbid` matches, the request is **denied**, regardless of any matching `permit`.
3. If **no** `forbid` matches and **at least one** `permit` matches, the request is **allowed**.
4. If **no rule matches at all**, the request is **denied** (default-deny / fail-closed).
`forbid` always wins. A `forbid` at organization scope cannot be overridden by a `permit` at agent scope. Design rules accordingly: broad restrictions at higher scopes, specific allowances at lower scopes.
## Effective policy
The effective policy is the merged set of all active rule bundles across the [scope hierarchy](/concepts/platform/scopes). Assembly works as follows:
1. Fetch the active bundle at each scope: organization, tenant, workspace, agent.
2. Merge Cedar files with scope-prefixed filenames (`org/rules.cedar`, `workspace/rules.cedar`) to prevent name collisions.
3. Compute a composite content hash from the merged file list.
4. Load the merged policy into the evaluator as a single PolicySet.
The gateway polls for content-hash changes on a sync interval (default: 10 seconds). When a bundle is deployed or rolled back, the hash changes and the gateway picks up the new policy on the next sync.
### Per-workspace vs per-agent evaluation
| Deployment | Evaluator | Use case |
| --------------------------- | ------------------------------------------------------------------------------ | -------------------------------- |
| **Hosted gateway** | `WorkspaceRuleEvaluator` maintains separate policy sets per assigned workspace | Multi-tenant shared gateway |
| **SDK / dedicated runtime** | `RuleEvaluator` uses a single workspace policy set | Dedicated per-service deployment |
Both evaluators enforce the same Cedar semantics. The hosted gateway adds per-workspace freshness checks. If a workspace's policy has not synced within its configured freshness window, requests are denied with a `authorization.staleness_rejected` audit event.
## Fail-closed behavior
The authorization model is fail-closed at every level:
* **No matching rule:** denied. When [Intelligent Authorization](/concepts/intelligent-authorization) convenes on live traffic, a `no_match` in a `live`-mode workspace can be overridden by a Court `permit`. Until then `no_match` always resolves to the default-deny.
* **Evaluator error:** denied.
* **Stale policy:** denied (hosted gateway only, per-workspace freshness window).
* **No policy loaded:** denied.
* **Court unavailable:** denied with `reason: "court_unavailable"` when fewer than two judges return a usable vote.
Cedar itself has no permissive or audit-only mode. Use [simulation](/govern/rules/simulate) to test rule changes before deploying. Intelligent Authorization `audit` mode is a separate construct. It records Court rulings without enforcing them so you can validate the panel before flipping to `live`.
## Next steps
With that Cedar evaluation model in mind, continue with:
* [Rules](/concepts/controls/rules) concept for bundles, scopes, and effective Rules
* [Rules](/reference/controls/rules) reference for entity, action, and attribute catalogs
* [Authorize Access](/govern/rules) to write, validate, simulate, and apply Rules
* [Permissions](/concepts/platform/permissions) concept for platform RBAC (separate from Cedar)
* [Scopes](/concepts/platform/scopes) concept for the hierarchy that feeds effective policy
# Data plane
Source: https://docs.domesystems.ai/concepts/architecture/dataplane
Why Dome puts a fail-closed runtime between agents and their tools and models
## High-level overview
The data plane is the process that enforces traffic to Gateway surfaces. A Gateway is the named access surface you configure (membership and grants).
Two **ingresses** share one engine, credential store, and audit pipeline. Both require a Gateway prefix on the wire:
* [Tools gateway](/concepts/gateways/tools-gateway) concept — MCP and related tool traffic at `/gateways//mcp`
* [LLM gateway](/concepts/gateways/llm-gateway) concept — OpenAI- and Anthropic-shaped model traffic at `/gateways//v1/...`
A request through the data plane looks like this:
1. An agent sends a request to `/gateways/