View as markdown

# Config Reference

A clawpatrol gateway config mixes operational settings in the required top-level gateway { ... } block with policy blocks. Policy blocks (approver, credential, tunnel, endpoint, rule) dispatch to a plugin chosen by the block's first label.

# How to read this page

Each block section lists the attributes the loader accepts, with:

• Type — the HCL value type. string, bool, int are scalar literals; []string is a list of strings; ref(<kind>) is a typed reference to another block (<type>.<name> for two-label kinds like credential = bearer_token.github, <kind>.<name> for one-label kinds like rule = rule.no-pii); []ref(<kind>) is a list of such references; nested blocks have their shape described inline.
• Required — yes if the loader rejects the block when the attribute is missing.

Plugin-dispatched kinds (approver, credential, tunnel, endpoint, rule) list one subsection per registered type.

# Top-level blocks

Operational settings live under the required top-level gateway { ... } block. The optional defaults { ... } block carries policy fallbacks. Labeled policy blocks (profile, approver, credential, endpoint, rule, tunnel) are documented in their own sections.

# gateway { ... }

The gateway block carries operational settings — listen addresses, the WireGuard / Tailscale transport sub-blocks, session and retention windows, telemetry, and the resolver.

Nested block limits {}:

The optional limits { ... } sub-block inside gateway { ... }. It exposes the two independent body-size limits as human-readable size strings (e.g. "256KiB", "1MiB"):

• BodyBuffer bounds the hot-path buffer the rules engine matches against. Trade-off: latency / memory vs. how much body rules see.
• BodyStorage bounds the cold-storage sample persisted per action. Trade-off: disk / db size vs. how useful the action details page is for debugging.

Both are independent: a deployment may log more (or less) than it rule-matches. Empty fields fall back to the DefaultBody*Limit constants, which equal today's hardcoded behavior.

Nested block genai_telemetry {}:

The body of the genai_telemetry { ... } sub-block inside gateway { ... }. Presence of the block enables emission of OpenTelemetry GenAI semantic-convention spans for intercepted LLM requests (gen_ai.* attributes — semconv v1.27.0).

Nested block wireguard {}:

The body of the wireguard { ... } sub-block inside gateway { ... }. Presence of the block enables the WG transport.

Nested block tailscale {}:

The body of the tailscale { ... } sub-block inside gateway { ... }. Presence of the block enables tsnet.

# profile "<name>" { ... }

Names a set of credentials. Profiles bind to dashboard owners; an owner's profile determines which credentials — and, transitively via each credential's endpoint / endpoints binding, which endpoints — their gateway requests can reach. Rules ride along automatically because they're attached to endpoints.

profile "default" {
  credentials = [bearer_token.github, postgres_credential.postgres-prod]
}

# approver blocks

Block syntax: approver "<type>" "<name>" { ... }

Registered types: human_approver, llm_approver.

# approver "human_approver" "<name>"

Targets one channel. Timeout / require_approvers override the global defaults block on a per-approver basis.

Credential references a credential whose body satisfies HITLNotifier (slack_tokens and signal_cli today; future Discord / Telegram / SMTP credentials). Leave empty for a dashboard-only approver (no channel notification; operator clicks approve/deny on the dashboard).

approver "human_approver" "example" {
  channel = "#approvals"
}

# approver "llm_approver" "<name>"

Carries the model + the credential used to authenticate the call to the model API + the inline policy text the model judges against. policy is a heredoc-friendly string attribute on the approver block itself — no separate policy "<name>" {} block.

approver "llm_approver" "example" {
  model = "claude-haiku-4-5-20251001"
  credential = bearer_token.example
}

# credential blocks

Block syntax: credential "<type>" "<name>" { ... }

Registered types: anthropic_manual_key, anthropic_oauth_subscription, aws_credential, basic_auth, bearer_token, clickhouse_credential, cookie_token, discord_bot_token, gemini_api_key, github_oauth, google_gke_credential, header_token, mtls_credential, notion_mcp_oauth, notion_oauth, openai_codex_oauth, passthrough, postgres_credential, signal_cli, slack_tokens, ssh_key, tailscale_auth, telegram_bot_token.

# credential "anthropic_manual_key" "<name>"

No configurable attributes.

credential "anthropic_manual_key" "example" {}

# credential "anthropic_oauth_subscription" "<name>"

No configurable attributes.

credential "anthropic_oauth_subscription" "example" {}

# credential "aws_credential" "<name>"

Schema is intentionally empty: access key id and secret access key (and optional session token) live in the secret store as named slots, filled via the dashboard or CLAWPATROL_SECRET__ env vars. Cluster + region come from the kubernetes endpoint at request time.

No configurable attributes.

credential "aws_credential" "example" {}

# credential "basic_auth" "<name>"

Injects Authorization: Basic <base64(username:password)>.

The credential secret is the raw password; username lives in config. Common credential binding fields apply: use endpoint or endpoints to bind the credential to upstreams.

When a profile has multiple Basic Auth credentials for the same HTTPS endpoint, use the placeholder disambiguator on the profile entry or credential block. The HTTPS placeholder detector matches that value inside decoded Authorization: Basic <base64(username:placeholder)> request headers.

credential "basic_auth" "example" {
  endpoint = https.example
  username = "example"
}

# credential "bearer_token" "<name>"

credential "bearer_token" "example" {}

# credential "clickhouse_credential" "<name>"

Database, when set, is the discriminator the dispatcher uses to pick this credential when several clickhouse_credential blocks bind the same endpoint(s). At request time the gateway reads the agent-declared database off the wire and picks the credential whose database matches; an unset database field is the catchall (one allowed per (profile, endpoint)).

credential "clickhouse_credential" "example" {}

# credential "cookie_token" "<name>"

credential "cookie_token" "example" {}

# credential "discord_bot_token" "<name>"

Injects Discord bot tokens for REST and Gateway SDK traffic.

No configurable attributes.

credential "discord_bot_token" "example" {}

# credential "gemini_api_key" "<name>"

No configurable attributes.

credential "gemini_api_key" "example" {}

# credential "github_oauth" "<name>"

No configurable attributes.

credential "github_oauth" "example" {}

# credential "google_gke_credential" "<name>"

No configurable attributes.

credential "google_gke_credential" "example" {}

# credential "header_token" "<name>"

credential "header_token" "example" {
  header = "X-API-Key"
}

# credential "mtls_credential" "<name>"

No configurable attributes.

credential "mtls_credential" "example" {}

# credential "notion_mcp_oauth" "<name>"

No configurable attributes.

credential "notion_mcp_oauth" "example" {}

# credential "notion_oauth" "<name>"

No configurable attributes.

credential "notion_oauth" "example" {}

# credential "openai_codex_oauth" "<name>"

No configurable attributes.

credential "openai_codex_oauth" "example" {}

# credential "passthrough" "<name>"

A credential that injects nothing. It exists only as a handle the operator declares, binds to endpoints, and lists in a profile's credentials — so the existing credential→endpoint→profile claim path works for endpoints that simply don't need auth injection (public APIs, services reached over an already-authenticated tunnel, open-internal endpoints). Write one passthrough credential per group of credential-less endpoints a profile should claim, or share one across several. The gateway forwards matching requests verbatim — no header, signature, or token rewrite — while the profile's rules still apply.

No configurable attributes.

credential "passthrough" "example" {}

# credential "postgres_credential" "<name>"

Database, when set, is the discriminator the dispatcher uses to pick this credential when several postgres_credential blocks bind the same endpoint(s). At request time the gateway reads the agent-declared database off the StartupMessage and picks the credential whose database matches; an unset database field is the catchall (one allowed per (profile, endpoint)).

credential "postgres_credential" "example" {}

# credential "signal_cli" "<name>"

A notification-only HITL notifier that delivers approval prompts to Signal via a signal-cli-rest-api instance (https://github.com/bbernhard/signal-cli-rest-api). Signal has no interactive buttons, so the prompt is plain text ending in an "Open dashboard" link where the operator approves or denies.

Connection details live in the secret store as named slots, filled via the dashboard: api_url (base URL of the signal-cli-rest-api), number (the registered E.164 sender), and auth (optional "user:pass" for HTTP basic auth). The recipient is the human_approver's channel - an E.164 number or a "group.".

DeleteOnDecision remote-deletes the prompt once the operation is decided, so a conversation does not fill up with dead approve/deny links. It runs off the runtime's HITLMessageUpdater hook - the same one the Slack notifier uses to edit its message - so a prompt is only ever removed after the decision lands, never on a timer while the operator is still expected to act.

Remote-delete needs a real peer: a group with another member, or a different number. It does NOT work for Note-to-Self (channel = the account's own number): signal-cli returns the sync-envelope timestamp for self-sends, not the message timestamp remote-delete needs, so the delete is a no-op on the linked phone.

credential "signal_cli" "example" {}

# credential "slack_tokens" "<name>"

No configurable attributes.

credential "slack_tokens" "example" {}

# credential "ssh_key" "<name>"

No configurable attributes.

credential "ssh_key" "example" {}

# credential "tailscale_auth" "<name>"

Has no operator-facing fields — there is nothing to paste. Per-tailnet selection (control_url, tags) lives on the tunnel block instead.

No configurable attributes.

credential "tailscale_auth" "example" {}

# credential "telegram_bot_token" "<name>"

No configurable attributes.

credential "telegram_bot_token" "example" {}

# endpoint blocks

Block syntax: endpoint "<type>" "<name>" { ... }

Registered types: clickhouse_https, clickhouse_native, https, kubernetes, openai_codex_https, postgres, ssh.

# endpoint "clickhouse_https" "<name>"

Family: sql.

endpoint "clickhouse_https" "example" {
  hosts = ["api.example.com"]
}

# endpoint "clickhouse_native" "<name>"

Addresses one ClickHouse server reachable via the binary native protocol. Operators bind a single clickhouse_credential; the runtime parses the agent's Hello and substitutes the credential's (user, password) where the agent embedded a placeholder.

TLS toggles TLS on both hops: the gateway terminates the agent's TLS using a leaf minted off the gateway CA, parses the Hello in plaintext, then re-wraps to upstream. The wrapped client therefore keeps speaking native-over-TLS exactly as it would against the real cloud ClickHouse — clawpatrol run is transparent to its TLS posture. Default false: WG-only deployments where the operator wants plaintext on the inner hop (typical self-hosted ClickHouse on 9000 behind a private network) leave it off.

AcceptInvalidCertificate mirrors clickhouse-client's flag of the same name: when true and tls is on, the gateway skips upstream cert validation. Use for self-hosted ClickHouse fronted by a private CA. Default false keeps full validation against system roots.

Family: sql.

endpoint "clickhouse_native" "example" {
  hosts = ["api.example.com"]
}

# endpoint "https" "<name>"

Family: http.

endpoint "https" "example" {
  hosts = ["api.example.com"]
}

# endpoint "kubernetes" "<name>"

ClusterName + Region are EKS auth parameters: when the bound credential is aws_credential, the gateway presigns an STS GetCallerIdentity URL scoped to (region, cluster_name) and stamps the result as a k8s-aws-v1.<…> bearer. Leave both unset for self-hosted clusters with a non-EKS credential (bearer_token, mtls_credential).

Family: k8s.

endpoint "kubernetes" "example" {}

# endpoint "openai_codex_https" "<name>"

Family: http.

endpoint "openai_codex_https" "example" {
  hosts = ["api.example.com"]
}

# endpoint "postgres" "<name>"

Addresses a single RDS-or-equivalent server. Tunnel topologies (kubectl-portforward-ssh and friends) aren't supported in this iteration — operators run the gateway with network reachability already arranged.

SSLMode mirrors libpq's sslmode names — "disable" / "prefer" / "require" / "verify-full". Default "prefer": try TLS, fall back to plain when the upstream replies 'N'. "require" hard-fails on 'N'. "verify-full" additionally validates the upstream cert against Host. "disable" skips the SSLRequest probe entirely — fine for self-hosted pg on a private network where WG already encrypts the path.

Family: sql.

endpoint "postgres" "example" {
  host = "db.internal:5432"
}

# endpoint "ssh" "<name>"

Binds one or more host:port tuples. The credentials that authenticate against it live on credential blocks via the framework-level endpoint = X / endpoints = [...] binding. When a profile wields more than one SSH credential at the endpoint, each ambiguous credential carries a user = "..." disambiguator — either on its profile-inline entry ({ credential = X, user = "..." }) or on the credential block itself — and the agent's wire-protocol username picks the matching entry. The agent's username is also passed through verbatim as the upstream SSH user; credentials carry only auth material (key / password / host_pubkey), never a username override.

Family: ssh.

endpoint "ssh" "example" {
  hosts = ["api.example.com"]
}

# rule blocks

Block syntax: rule "<name>" { ... }

# rule "<name>"

The gohcl-tagged decode target. The match predicate is family-agnostic at the HCL layer (just a CEL string); the facet's *cel.Env decides which variables are valid once the family has been inferred from the endpoint refs.

rule {}

# tunnel blocks

Block syntax: tunnel "<type>" "<name>" { ... }

Registered types: kubernetes_port_forward, local_command, ssh_port_forward, tailscale.

# tunnel "kubernetes_port_forward" "<name>"

Configures the tunnel runtime.

tunnel "kubernetes_port_forward" "example" {
  port = 30
}

# tunnel "local_command" "<name>"

Configures the tunnel runtime.

tunnel "local_command" "example" {
  command = ["example"]
  listen = "example"
}

# tunnel "ssh_port_forward" "<name>"

Configures the tunnel runtime.

tunnel "ssh_port_forward" "example" {
  bastion = "bastion.example:22"
  user = "example"
  credential = bearer_token.example
}

# tunnel "tailscale" "<name>"

Configures the tunnel runtime.

tunnel "tailscale" "example" {}