Skip to content

sentry.toml: The Deployment Configuration

Argus Sentry reads one annotated configuration file, sentry.toml. The file is the single source a deployment edits. The loader, argus_sentry.config.load_config, parses it with the Python standard library's TOML reader and builds the typed objects the shipped components consume. One annotated copy ships inside the package with every key documented: its type, its default, and the component that consumes it.

The loader is wire-through only. It constructs the shipped components with their existing signatures and changes no behavior.

The fail-closed load contract

Validation happens at load, before the boundary accepts a single call. A configuration that does not parse clean never starts.

Condition Result
Unknown key in any section ConfigKeyError naming the key; load fails
Malformed value ConfigTypeError naming the key and the expected type
Missing key type in a key reference ConfigError; the two accepted forms are named in the message
Inline key material ConfigError: key material is never inlined
Referenced policy file does not exist ConfigError; load fails
Referenced key file unreadable, empty, or not 32 bytes of hex ConfigError naming the file
Referenced environment variable unset ConfigError naming the variable

An unknown key is a rejected deployment, not a warning. A typo in a key name cannot silently fall back to a default.

Key material is referenced, never inlined

Every key entry names a source. The material itself resolves at build time and never appears in the configuration:

[issuer]
key = { type = "file", path = "keys/issuer.hex" }        # 64 hex chars = 32 bytes
[issuer]
key = { type = "env", name = "ARGUS_SENTRY_ISSUER_KEY" }

Inline material is rejected at parse time:

[issuer]
# Rejected: key material is never inlined.
key = { type = "inline", hex = "3fa7..." }

The error names the two accepted forms. This holds for every key entry in the file: the issuer seed, the chain record key, the load authority key, the host attestation key, and the policy trust anchor.

The sections

Section The deployment decides Notes
[deployment] Form (embedded / sidecar / sharded), server id, audience, listener, shard worker count The audience is the token audience executors verify; both ends must agree
[policy] Policy path, trusted signer id, signer verify key Paths resolve against the file's directory; the policy file must exist at load
[issuer] Token mode (ed25519 / session-hmac), key id, epoch, TTL, signing key Key ids from 0x8000 up are the reserved session range and are rejected
[session] Session TTL, action-class scope, target bounds, token limits Applies in session-HMAC mode; a session states its grant or assembly refuses
[executor] Amount pointer, clock skew, replay store sizing The amount pointer is where monetary limits read the action amount
[evidence] Recorder contract (auto / native / reference), inline or async, batch size, chain keys Batch size 2 to 4096 anchors one signed record per batch
[retention] Record classes, dispositions, mode (worm / audit-trail) Unmapped classes are never dispositioned
[oversight] Hold-queue capacity and TTL A full queue leaves denials standing; an expired hold never approves
[model] Model identity and version pin Both fields, or none; a deployment that pins none records the absence
[engine] Engine binding demand (auto / native / reference) native feeds the health readiness gate
[host] Host attestation key Signs every proposal's host attestation and each batch root
[metrics] Metrics hook, ring capacity, profile label Off by default

What the load verifies beyond shape

The policy named in [policy] must carry a valid Ed25519 signature over its canonical signed range, verified against the trust anchor named by signer and anchor. An unsigned policy, a signature from an untrusted key, or any post-signature edit fails closed before a single call is evaluated.

In session-HMAC mode the session must state its grant: a list of target patterns, or an explicit unrestricted = true. A configuration with neither refuses to assemble.

See Packaging and Health Readiness for the install path and the readiness gate that checks the configuration's demands at runtime.