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 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 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, 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, 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 "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 "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" {}