View as markdown

# Glossary

# The big picture

Claw Patrol sits between an agent and the upstream services it talks to. Operators describe the system with endpoints, credentials, rules, approvers, and profiles. This page defines those terms; see Architecture for traffic flow and Config Reference for HCL fields.

# Concepts

# Gateway

The Claw Patrol daemon. It loads config, hosts the operator UI, applies policy, injects real credentials, and forwards allowed traffic upstream. See Architecture for the gateway’s position in a deployment.

# Agent

A program whose outbound traffic is routed through the gateway — typically an AI coding agent (Claude Code, Codex, OpenClaw) or a custom script. The agent never holds real credentials; it sends placeholders and the gateway swaps them at the wire. "Agent" is the who of a request; device is the where it came from used by the global config.

# Device

A machine whose traffic is routed through the gateway. The gateway recognizes a device as the source identity for a request, and operators assign each device one profile.

# Endpoint

A typed network target — a name, a protocol family (http / sql / k8s), and the host(s) it claims. Endpoints are pure network targets: hosts plus protocol-family connection parameters, nothing more. The unit a rule attaches to. See Config Reference for endpoint schemas.

# Credential

A typed handle to a secret for one or more endpoints. The config block describes where the secret should be injected; the secret bytes stay in the gateway’s secret store. See Config Reference for credential schemas.

# Action

One unit of agent work the gateway sees and applies policy to — one HTTP call, one SQL query, one kubectl invocation, one SSH command. Each action targets an endpoint, is gated by the matching rule's outcome, and surfaces in the dashboard’s live request feed. "Action" is the operator-visible concept of "the thing the agent did."

# Rule

One policy decision targeting one or more endpoints. A rule has a CEL condition string that matches against the facets of the rule’s protocol family (inferred from its endpoints), an optional credential predicate, and an outcome — either a literal verdict or an approve = [...] chain. See Rules for family-specific matching and examples.

# Facet

A single named matchable property exposed to a rule's CEL condition, such as the HTTP method, SQL tables, or Kubernetes resource. Each protocol family exposes its own facets. See Rules for the full list.

# CEL condition

The boolean expression a rule's condition = "..." field carries. CEL (Common Expression Language) is evaluated against the facets of the rule’s inferred family. An absent or empty condition matches every request the rule’s endpoints see.

# Approver

An entity that arbitrates an approve = [...] chain stage. Built-in types: llm_approver (Claude / GPT proctor that reads a policy prompt) and human_approver (Slack / dashboard, with optional N-of-N quorum).

# Profile

A named list of credentials attached to a device. Endpoint membership follows the credentials in the profile, so profiles are how operators say "these are the secrets I want this device to wield."

# Plugin

A (kind, type) extension — e.g. (endpoint, http), (credential, bearer_token), (approver, human_approver). Plugins add new config block types and the behavior behind them. See Plugins.

# Outcome

The decision a matched rule carries: verdict = "allow", verdict = "deny", or approve = [...] (an ordered list of approver stages). Human approval pauses the request before upstream forwarding while the approver decides. On allow, the credential plugin’s runtime stamps the secret onto the forwarded request.

# Placeholder

A magic string an agent embeds in the auth slot when its profile wields more than one credential at the same endpoint. The profile’s credentials list mixes bare-name entries with inline { placeholder = "PH_...", credential = name } objects that name the discriminator for each ambiguous credential; the gateway looks at the incoming request, picks the matching credential, and substitutes the real secret. Placeholders live on the profile (not the credential) because the ambiguity exists only when one identity actively uses multiple credentials at one endpoint. The agent never holds the real key — only the placeholder.

# Secret store

The gateway-side source of secret bytes. Default backend: environment variables, keyed by CLAWPATROL_SECRET_<UPPER_NAME> (with @/path/to/file shorthand for reading PEM bundles off disk).

# MitM

"Man-in-the-middle" — the gateway’s TLS interception strategy. It allows the gateway to inspect and authorize encrypted protocol traffic before forwarding it upstream. See Architecture › MitM TLS Interception.

# Per-host cert

A certificate the gateway generates for a specific upstream host during MitM TLS interception.

# Auth offload

The gateway performs an upstream authentication handshake on behalf of the agent, using the real credential while keeping that credential out of the agent process.

# Config mapping

The HCL file is where these concepts are declared. This section only maps concepts to their config homes; use Config Reference for exact fields, types, and examples.