Gatekeeper configuration file · Confidential Router

Where the gatekeeper looks for config.yaml on each operating system, and every key in it with its default.

Where the file lives

The default is confidential-gatekeeper/config.yaml inside your user configuration directory, which is not the same place on every system:

System	Default path
Linux	`$XDG_CONFIG_HOME/confidential-gatekeeper/config.yaml`, or `~/.config/confidential-gatekeeper/config.yaml` when that variable is unset
macOS	`~/Library/Application Support/confidential-gatekeeper/config.yaml`
Windows	`%AppData%\confidential-gatekeeper\config.yaml`

Four layers decide which file is used, strongest first: the --config flag, $CR_GATEKEEPER_CONFIG, $GATEKEEPER_CONFIG, then the default above. Rather than work it out, ask:

sh
gatekeeper config path

It prints the file this invocation would use and which of the four layers chose it.

The trust and endpoint commands edit that file in place and keep your comments. The normative schema is schemas/gatekeeper-config.schema.json in the repository.

The file

yaml
version: 1trustedRoots:  - name: swarm-cloud-prod    pemFile: ./roots/swarm-cloud-prod.pemattestedRoots:  enabled: true  requireNetworkType: any  cacheTtl: 10m  checkRevocations: false  registryBaseUrl: https://raw.githubusercontent.com/Super-Protocol/sp-vm/main/signatures  trustedMeasurements: []policies:  - name: images-from-our-registry    file: ./policies/images.regodefaults:  failMode: closed  reattestInterval: 5m  verdictCacheTtl: 60s  maxBundleAge: 24h  initialTimeout: 15sendpoints:  - name: router    listen: 127.0.0.1:8787    upstream: https://api.router.superprotocol.com    trust: evidence-digest    trustedEvidence:      - sha256:402198e23bc1bcd505a34d6cb28accd98f400e5444b0ca3a2d1e09d45ab72fc1    reattestInterval: 2mlog:  level: info  format: textadmin:  listen: unix:/run/user/1000/gatekeeper.sockaudit:  file: ~/.local/state/confidential-gatekeeper/audit.logmetrics:  listen: 127.0.0.1:9464

Keys

Key	Default	Meaning
`version`		Always `1`
`trustedRoots[]`	`[]`	Manually trusted roots, matched by the SHA-256 of the root's DER. `name` plus `pemFile` or an inline `pem`. May stay empty because of `attestedRoots`
`attestedRoots.enabled`	`true`	Accept a root when its own TEE evidence proves it is a Super Swarm root
`attestedRoots.requireNetworkType`	`any`	`trusted` also requires the root to declare a trusted network
`attestedRoots.cacheTtl`	`10m`	How long one root's verdict is reused
`attestedRoots.checkRevocations`	`false`	Also consult the CPU vendor's revocation lists; needs network
`attestedRoots.registryBaseUrl`	the `sp-vm` signatures directory on GitHub	Where signed measurements are read from; this only moves the mirror, the signing key is pinned in the binary
`attestedRoots.trustedMeasurements[]`	`[]`	Measurements you accept yourself, in addition to the registry-signed ones; written by `trust measurements add`
`policies[]`	`[]`	Rego modules, each with `name` and `file`, ANDed with the built-in pin policy
`defaults.failMode`	`closed`	`closed` answers 503 while there is no valid verdict; `open` proxies anyway, logs a warning and marks the response
`defaults.reattestInterval`	`5m`	Background re-verification period
`defaults.verdictCacheTtl`	`60s`	How long an on-demand re-check reuses a verdict
`defaults.maxBundleAge`	`24h`	A bundle older than this is stale
`defaults.initialTimeout`	`15s`	How long the first request waits for a verdict
`endpoints[].name`		The endpoint's name in every command and report
`endpoints[].listen`		Local `host:port`
`endpoints[].upstream`		`https://host` of the router endpoint
`endpoints[].trust`	`evidence-digest`	What the built-in policy requires; see below
`endpoints[].trustedEvidence[]`		Pinned evidence digests; hex, `sha256/<base64url>`, `sha256/<hex>` or bare hex all load
`endpoints[].<any defaults key>`		Overrides the global default for this endpoint
`log.level`	`info`	`debug`, `info`, `warn`, `error`
`log.format`	`text`	`text` or `json`
`admin.listen`	unset	Loopback address or Unix socket for `gatekeeper status`
`audit.file`	unset	One JSON object per line: every verdict and every blocked request, never a body
`metrics.listen`	unset	Prometheus endpoint, off unless set

Trust modes

endpoints[].trust is one of three values. The commands only ever write the first.

Mode	Admits when	Who it is for
`evidence-digest`	the deployment's digest is in `trustedEvidence`	Everyone: "this exact deployment"
`cloud-measurement`	the cloud's measurement is in `attestedRoots.trustedMeasurements`; `trustedEvidence` must be empty	A caller that registers upstreams at runtime and accepts any deployment on a listed cloud. It gives up the per-deployment guarantee
`measurement-and-digest`	both: the measurement is listed and the digest is pinned; neither has to be configured for the file to run	The router's own egress toward external endpoints; the first verification is how the console learns what to approve

In the last two modes the measurement list is the sole authority: a registry-signed cloud you did not list is denied. A denial in measurement-and-digest names the missing factor with a refusal code: digest-not-pinned, measurement-not-trusted or digest-mismatch.

Environment overrides

Every key under defaults has CR_GATEKEEPER_<KEY> globally and CR_GATEKEEPER_ENDPOINT_<NAME>_<KEY> per endpoint, upper-cased with underscores, for example CR_GATEKEEPER_ENDPOINT_ROUTER_FAIL_MODE. $CR_GATEKEEPER_CONFIG names the file.