Configuration

Read this if you are setting up or changing laidline.yaml. You will find every section and key, its default and what it changes. Skip if you only want a first marked file (Quickstart) or a production checklist (Production). Time: look up a key in a minute. Needs: Laidline installed; some keys need an extra (image, audio, video, text, server, kms, evidence).

In short

• One YAML file plus LAIDLINE_<SECTION>__<KEY> environment overrides; environment beats the file, the file beats defaults.
• laidline init writes a starter file; the sections it leaves out take their defaults. An unknown top-level section stops the load.
• An unset LAIDLINE_ENV means production: every relaxed check needs LAIDLINE_ENV=development exactly.
• laidline serve binds 127.0.0.1; server.max_upload_bytes (64 MiB) caps every request body and server.mark_token_env adds an inbound token.
• Licence and issuer settings never stop marking: every outcome is a reported state.

Laidline reads one YAML file plus environment overrides. Lookup order: an explicit path (Marker.from_config(path), --config), then LAIDLINE_CONFIG, then ./laidline.yaml, then /etc/laidline/config.yaml. Relative paths inside the file resolve against the file's directory. laidline init writes a starter file; the sections it leaves out (server, media, licence, ingest, upstream, assets and adapter) take their defaults.

The top-level sections are system, signing, watermark, evidence, on_mark_failure, detect, ingest, upstream, assets, adapter, admin, jobs, licence, issuer, server and media. Any other top-level key stops the load with unknown top-level section(s): <names> (known: ...), so a typo such as evidnce: fails instead of silently falling back to defaults. A top-level cloud: key is ignored with a warning. Keys inside a section are not checked this strictly: an unknown nested key is ignored, except where a section says that a misspelt key is an error.

Any key can be overridden with LAIDLINE_<SECTION>__<KEY> (double underscore per nesting level), for example LAIDLINE_SIGNING__TSA__REQUIRED=false or LAIDLINE_SYSTEM__NAME=acme-flux. Environment beats the file; the file beats defaults. Two variables are read directly rather than through the model: LAIDLINE_CONFIG (file path) and LAIDLINE_ENV (see "Environment" below).

Environment

LAIDLINE_ENV has one rule: unset means production. Every relaxed check needs LAIDLINE_ENV=development exactly: an inline payload-key secret, a secret file readable by others, the published test secret and issuer.extra_roots_file are refused or ignored otherwise. The one setting keyed to the word production itself is the local PEM signing backend, which laidline init writes for a first run: it is refused only under an explicit LAIDLINE_ENV=production unless signing.local.allow_in_production is true. Set LAIDLINE_ENV=production on every production host so a leftover local key cannot sign there.

LAIDLINE_MODELS_MIRROR (default unset) is the https base URL of a Laidline mirror of the model weights, for example https://laidline.com/models (Laidline's own mirror; you can point it at your own copy instead). When it is set, Laidline fetches each missing AudioSeal, VideoSeal, PixelSeal and TrustMark Q decoder graph (trustmark/decoder_Q.fp32.onnx) file from <base>/<file> first and from the URL pinned in the package second. The graph's pinned URL is that same Laidline mirror, https://laidline.com/models/trustmark/decoder_Q.fp32.onnx; the other files are pinned to their upstream hosts. Every source is checked against the same pinned SHA-256 and size, so the mirror is a convenience and never a trust root. There is no configuration-file key for it. laidline models fetch prints the host each file came from.

system

signing

With neither keys nor keys_file, the single-key fields (backend, local, aws, vault, cert_chain_path) form a keyring of one key with id default, as before.

An explicit roots_path: null keeps verification of the TSA tokens off. If your laidline.yaml has that line, change it to roots_path: builtin, or delete it to take the default. A file that never sets the key already verifies the default TSAs' tokens.

signing.keys and signing.keys_file (key rotation)

A keyring lists several signing keys with validity windows; Laidline signs with the one active now and switches at the boundaries without a restart. The rotation runbook is in Certificates and keys.

signing:
  # created and updated by `laidline keys rotate`; relative to this file
  keys_file: ./keys.yaml
  tsa: { ... }                       # stays here; shared by every key

# keys.yaml as `laidline keys rotate` writes it (paths relative to this file, times in UTC)
version: 1
keys:
- id: default
  backend: aws-kms
  aws:
    key_id: arn:aws:kms:eu-central-1:111122223333:key/...
  cert_chain_path: certs/chain-2026.pem
  not_after: '2026-10-01T00:00:00Z'
- id: k2026b
  backend: vault-transit
  vault:
    addr: https://vault.internal:8200
    key_name: laidline
    key_version: 3
  cert_chain_path: certs/chain-2026b.pem
  not_before: '2026-09-30T00:00:00Z'

Selection at any moment: keys whose not_after has passed are retired and never used; among the rest, the active key is the one with the latest not_before that has passed (no not_before counts as the earliest), and a tie goes to the later entry in the list. The others are standby (started but superseded) or scheduled (not_before in the future). Every non-retired key is built at start and at each reload (KMS and Vault calls happen then, never on the mark path), and each chain is validated at max(now, not_before). Loading fails when no key is active; once every key has retired, marks fail with signer_unavailable; if a later key is scheduled, marks resume at its not_before without a reload (until then, timer checkpoints keep signing with the previous key).

A switch, scheduled or by reload, appends a config_changed entry (Evidence log). SIGHUP (laidline serve, laidline ingest) or POST /admin/reload re-reads the keys (the keys file, or the inline or single-key fields of the configuration loaded at start) and their chain files; nothing else in the configuration is reloaded. The keys file is locked with fcntl.flock on <keys_file>.lock, so keys rotate works on POSIX systems only.

signing.vault

Used by backend: vault-transit (hvac, in the kms extra). The key must be a Transit key of type ecdsa-p256; Laidline signs the SHA-256 digest (prehashed, marshaling_algorithm: jws), so the private key never leaves Vault. Policy and certificate steps are in Certificates and keys.

The evidence log records the key as vault-transit:<mount>/<key_name>@v<version> (c2pa.key_id, the checkpoint signer.key_ref).

watermark

Decode: the fast decoder and the hardened decode

Each detector can read a mark two ways. The fast decoder (decode: fast) is a quick first look: it runs the open model's own detector (or a faithful re-implementation of it) once and catches a mark that is clearly present. The hardened decode (decode: hardened) is the product: soft-decision decoding, searches and calibrated gates with measured false-accept bounds. It is the default for image.decode (TrustMark scheme), video.decode and text.decode; audio.decode: auto resolves to it when the audio detector runs on a usable CUDA device and to the fast read otherwise. For audio, VideoSeal and text the fast read is the hardened decode's first stage, so a mark the fast read finds is reported as found by it (decode_path: fast). For TrustMark images and the keyframe scheme the hardened decode does not run the fast decoder at all; there fast is a separate, cheaper opt-out with its own false-accept behaviour, stated in each row below. Choose fast only where the hardened decode's cost cannot be met (costs are given per row). "Fast" names the decoder only; it is unrelated to the x264 preset video.preset: fast and to the audio phase-search grids. PixelSeal, the default image scheme, has one decoder and ignores image.decode. Video and text marking are off by default, so those decode defaults apply once they are enabled.

watermark.image.scheme: pixelseal (the default) embeds PixelSeal's 256-bit message: the 61-bit payload and its CRC-16 in BCH(127, 78) with t=7, sent twice (laidline.watermark.image_code). Detect reads the image directly; when that finds nothing it reads the image cut to its largest non-uniform rectangle (a screenshot's photo, when the image has a flat border), the image turned half a turn and the photo found inside a page capture (a screenshot with browser bars around the photo; laidline.watermark.image.localise), and accepts a payload only when exactly one distinct payload appears across those reads (two are ambiguous: no payload). Each read decodes with Chase-II (12 flips) and needs the CRC-16 and payload version 1. deep_scan: true adds, only when the default reads find nothing, the six other dihedral turns of the image and the seven other turns of the photo box. Registry confirmation compares the recorded fingerprint with the view that decoded and, when that does not confirm, with up to 18 fingerprints: the decoded view and the photo box in their 8 dihedral turns, the query and its cut upright. So a screenshot or a turned copy can reach grade B when one of those matches; a payload without a confirmed registry hit is grade C at most. The measured rates, the analytic false-accept bound and the timings are in Grading ("PixelSeal image scheme"). The weights (a pinned 1.24 GB checkpoint, kept beside the 309 MB slim model derived from it: 1.55 GB in models/pixelseal) download on first use like AudioSeal's and VideoSeal's; laidline models fetch (--image) fetches and slims them ahead of time. image.decode and the three gate keys below apply to the trustmark scheme only.

watermark.image.decode: hardened reads the TrustMark decoder's outputs before thresholding, decodes bits 0-95 with strict BCH_5 over Chase-II flips (the four version bits are ignored, so a flipped schema bit no longer loses the image) and accepts the best candidate only when its signed score and its normalised score both reach the gates and its payload version is 1 (a best candidate with another version is rejected; the next one is not tried). Variants run in the configured order and the first accepted one wins. The defaults were fitted on one half of the step-1 bench arrays and checked on the other half (laidline.bench.image_calibration; numbers and the validation history in Grading). Lowering either gate below its default gives up that measured false-positive budget, and Laidline logs a WARNING when it does: without the gates the same decoding returns a payload for 1,526 of 2,500 unmarked photos (61 percent, fit half). The gates do not stop confident wrong payloads on crops and rotations of marked images (Grading). Grading does not change: a payload still needs a confirmed registry hit for grade B. The video keyframe scheme (video.scheme: trustmark_keyframes) keeps the fast decoder under watermark.image.decode: hardened; watermark.video.decode: hardened replaces its key-frame vote with a vote of the hardened decoder and adds a window scan with the same decoder.

watermark.audio

AudioSeal on audio (audio): the library, /v1/mark/audio, ingest, the speech proxy and the streaming plugins. Needs the audio extra; without it audio calls fail with audio_unavailable.

watermark.video

VideoSeal or keyframe TrustMark on video (video): the library, the async job path (POST /v1/mark/video) and ingest. Needs the video extra; the audio track also needs audio.

watermark.device places VideoSeal and AudioSeal: auto embeds AudioSeal marks on the CPU, and runs AudioSeal detection and VideoSeal on cuda:0 when torch sees a GPU it can run, else the CPU (audio detection under auto uses the GPU; where marks are embedded does not change); on such a host the AudioSeal generator (embedding) stays on the CPU and the two AudioSeal detectors run on the GPU, so the process holds one copy of each model on the device that uses it: the generator's weights in CPU memory, the detectors' weights and their activations in GPU memory; cpu, cuda or cuda:N forces both, and a cuda value without a visible GPU stops the start with a configuration error. So does a GPU whose architecture the installed torch has no kernels for (kernels of the same major with an equal or lower minor, or PTX at or below the GPU's capability, count, so the cu130 wheels run everything from compute capability 7.5 up, an 8.9 L4 or a 12.1 GB10 included, and refuse a 7.0 V100); with auto, VideoSeal then runs on the CPU and a WARNING says why. The CUDA image needs driver R580 or newer (Video). The image scheme runs where watermark.image.device says (default cpu); the keyframe scheme reuses the image watermarker when it is TrustMark, and runs its own TrustMark on the CPU when image watermarking is off or uses PixelSeal. Weights for AudioSeal and VideoSeal are not bundled: they download on first use into $LAIDLINE_HOME/models (~/.cache/laidline/models without it), pinned by SHA-256; laidline models fetch downloads them ahead of time and LAIDLINE_OFFLINE=1 forbids the download (it does not change timestamping: see tsa.required).

watermark.cuda_precision sets how those models compute on a GPU. With strict (the default), the first time Laidline places a model on a CUDA device (AudioSeal detection, VideoSeal, or the image scheme under watermark.image.device), and before that model loads, it sets torch's torch.backends.cuda.matmul.allow_tf32 and torch.backends.cudnn.allow_tf32 to False, torch.backends.cudnn.deterministic to True and torch.backends.cudnn.benchmark to False, and logs this once. These four flags are torch's own, and they are process-wide: Laidline runs inside your process, so they also apply to any other torch work in that process (your own models run at full float32 too, which can be slower on GPUs that support TF32; Laidline's own AudioSeal and VideoSeal detection showed no material change on an RTX 5080). Laidline sets them once; a value your code sets after that stands. With default, Laidline leaves the flags as torch or your code set them (torch's default allows TF32 in cuDNN convolutions on Ampere and newer GPUs); if another Laidline instance in the same process already set strict, the flags stay strict and a WARNING says so. A CPU-only deployment is unaffected either way.

strict is the default because every detection figure Laidline publishes for a GPU was measured at full float32 with deterministic cuDNN, and TF32 changes the arithmetic enough to move decisions whose statistics sit close to a threshold: on 350 hard audio clips, the GPU detector under torch's default TF32 decided differently from the CPU on 9 units (presence on 4 of them, the decode path on all 9); at full float32 no decision differed and the path on 1 (Robustness baseline, "GPU against CPU, as shipped"). TF32's effect also depends on the GPU generation and the cuDNN version, so a TF32 figure measured on one host would not transfer to another. Choose default only if the process-wide setting conflicts with other work in the process and you accept detection on the GPU that may differ, on near-threshold inputs, from the published figures and from a CPU deployment.

watermark.text

Text is marked by the laidline-vllm plugin or laidline-transformers, both reading this section, and logged by the proxy (vllm). The plugin, the proxy and the detector must share key_seed and key_id.

watermark.payload_keys

Keyed watermark payloads (Payload keys says what a key does and does not do). Image, video and audio marks are keyed in keyed mode (the keyframe scheme's layout is carried and read by TrustMark Q alone; audio carries audioseal-p70-r1 unless watermark.audio.payload.layout: none). What else changes in keyed mode: /detect serves the public response tier (detect.unauthenticated), the public tier shows only the presence of an audio watermark, key events are recorded in the evidence chain, and the S3 sink writes two decoy objects. Absent (or mode: unkeyed): the unkeyed formats and grading, and a startup WARNING when image, video or audio marking is enabled. laidline init writes the section enabled, with a payload-k1.key secret file (mode 0600) beside the configuration. The environment overrides apply here too: LAIDLINE_WATERMARK__PAYLOAD_KEYS__MODE=unkeyed switches keyed mode off and LAIDLINE_DETECT__UNAUTHENTICATED=full serves the full result to everyone, so whoever sets the process environment controls both.

Exactly one of secret_file, kms_ciphertext_file, secret_env (or, in development, secret) per key. A secret that is not 64 to 128 hexadecimal characters, or repeats one byte value, is refused, and so is a published example secret (a deny-list) unless LAIDLINE_ENV is explicitly development; an unset LAIDLINE_ENV is strict (see Environment). The live-key limits hold for every medium, its marking enabled or not. A misspelt key in this section, detect.credentials, detect.state or detect.alerts is an error. Error messages name the key id, never a value.

evidence

Authority and failures. sinks[0] is authoritative: detect and the ingest duplicate check read through it (file: a linear scan of the directory; S3: pointer objects; Postgres: indexed columns), and laidline evidence export reads it unless --sink says otherwise. A failed write there fails the mark with evidence_unavailable under both on_mark_failure policies: fail_open would log its unmarked entry to the same primary, and no asset is ever returned without its log entry. Later sinks are best-effort replicas: a failed write there is logged, counted (laidline_evidence_sink_failures_total{sink="<type>:<index>"}) and skipped, the chain advances, and a verify of that replica shows the gap. For detect at scale, Postgres is the recommended primary (indexed lookups, one INSERT per entry); an S3 Object Lock bucket makes a good WORM replica, or a primary where marking volume is modest (every marked entry costs three S3 PUTs in two sequential phases, see Benchmarks).

Async replicas (replicas: async). Each replica gets a FIFO queue of replica_queue_max entries and its own writer thread; the mark pays only the primary write. A failed replica write is retried twice (0.5 s, doubling). The trade:

• the replica lags the primary, and a reader of the replica may briefly see a checkpoint before the entries it anchors have landed there;
• a full queue drops the entry: it is counted in laidline_evidence_sink_failures_total and laidline_evidence_replica_dropped_total, and logged once per overflow episode;
• at shutdown close() drains for up to replica_drain_timeout_s; entries still queued then are counted in laidline_evidence_sink_failures_total only (laidline_evidence_replica_dropped_total counts full-queue drops). A crash or SIGKILL before close() loses whatever is queued, without counting it;
• verify on the replica reports every gap later, not at mark time.

Watch laidline_evidence_replica_queue_depth (or replica_queue_depth in GET /admin/evidence/status). Measured guidance (Benchmarks): an S3 write in the bucket's region costs p50 54.9 ms and p95 77.0 ms, so sync stays the default and the recommendation in region; use async for an S3 replica in another region or behind a long network path (p50 533 ms, p95 556 ms from outside the region).

Keep credentials out of the file: S3 uses boto3's default chain (environment, profile, instance or task role), and Postgres should read its DSN from dsn_env. One process has one boto3 default session, shared by every S3 sink and the S3 ingest store, so they all use one set of credentials: an AWS primary plus an R2 or SeaweedFS replica that needs different credentials is not possible in one process.

type: file

type: s3

S3, or an S3-compatible store through endpoint_url (the evidence extra brings boto3).

type: postgres

PostgreSQL through psycopg 3 (evidence extra). Set up the schema with laidline evidence init-db (Evidence log).

Top level and detect

licence and issuer

See Licensing and metering. Two top-level sections of the configuration file; relative paths resolve against the config file's directory, and files left null default to that directory too. No value here can stop or change marking: every outcome is a reported state.

licence:
  # null: licence.d beside the config file; LAIDLINE_LICENCE overrides
  path: null
  clock_skew_s: 300
  status_interval_s: 60
  expose_state_header: false
  auto_fetch: true                    # false: never ask the issuing service for a renewed licence
issuer:
  certificate_path: null              # null: issuer-certificate.json beside the config file
  previous_ids: []
  registration_url: https://issue.laidline.com/v1
  extra_roots_file: null
  usage_report: true
  directory: {path: null, refresh_url: "https://directory.laidline.com/directory.json", stale_after_days: 120}

watermark.issuer_id keeps its only rule: an integer 1 to 65,535 when image, audio or video marking is enabled. The range a number falls in (registered 1 to 32,767, trial 32,768 to 65,279, reserved 65,280 to 65,535) is reported, not enforced.

ingest

Used by laidline ingest (aws-s3-sqs).

List values can be overridden from the environment with JSON, for example LAIDLINE_INGEST__PREFIXES='["a/","b/"]'.

upstream

Used by the OpenAI-compatible proxy in laidline serve (openai-proxy).

assets

Local store for image responses the proxy returns as url (served at GET /v1/assets/{name}).

jobs

The async job path of laidline serve (POST /v1/mark/video, GET /v1/jobs/{id}; video). The store and the worker exist only when watermark.video.enabled is true.

Jobs are local to one process. Status polling needs sticky routing by job id, or a single replica. On Cloud Run, deploy with CPU always allocated (--no-cpu-throttling), or the worker thread stops between requests. At shutdown the running job gets up to 30 s and queued webhooks up to webhook_timeout_s more, about 41 s in all, which is longer than Kubernetes' default 30 s grace period.

adapter

Generic JSON adapter rules for laidline serve: each rule is a route whose upstream response has its images marked in place. Rule fields, kinds, errors and what was proven are in generic-adapter.

A rule's upstream takes the same keys as the upstream section, flavor included, and defaults to that section.

An empty fetch_hosts allows any host, loopback and link-local addresses included: set it on every url rule.

server

laidline serve binds 127.0.0.1 unless started with --host 0.0.0.0 (the Docker images do that). server.max_upload_bytes (default 67108864, 64 MiB) bounds every request body: mark and detect uploads with room for multipart framing and base64, OpenAI proxy and adapter bodies at the cap itself, and video uploads under jobs.max_upload_bytes instead. Past it the mark, proxy and adapter routes answer 413 upload_too_large and /detect 413. A request whose Content-Length already exceeds it is refused before its body is read; a body sent without a length is cut at the cap as it arrives. server.mark_token_env (default unset) names an environment variable; while that variable holds at least 32 characters, every route except /healthz, /readyz, /metrics, /detect, /v1/assets/* (unguessable capability URLs for end users' browsers) and /admin/* (which has its own token) needs Authorization: Bearer <token> and answers 401 unauthorized without it. The variable is read on every request, so rotating it needs no restart; unset or shorter than 32 characters, the routes are open and start-up logs a warning. The token is removed before a request is proxied, so an upstream.auth: passthrough upstream receives no key: use upstream.auth: env with it. MarkClient sends LAIDLINE_API_KEY as the token. The cap on image size is in media.

media

Limits on the media Laidline decodes.

admin

Token-gated routes under /admin on laidline serve: POST /admin/reload (signing keys), GET /admin/evidence/status and GET /admin/evidence/export?from=...&to=...[&sink=N] (Evidence log).

While the variable is unset or shorter than 32 characters the routes do not exist: every method and path under /admin answers 404, as an unknown path does. With a token set, callers send Authorization: Bearer <token>; any request without the right token, on any /admin path (unknown ones included), is 401. The token is read on every request, so setting or rotating it needs no restart, and it never reaches logs, error bodies, evidence or metric labels. Keep /admin reachable from your own network only.

The export runs inside the serving process, one at a time per process (409 export_in_progress; several processes or replicas can each run one). The bundle is built in memory and in a temporary directory before its size is checked, so memory use is bounded by the range, not by export_max_bytes: size export_max_days to your volume, or export large ranges with laidline evidence export.

Reference

• Quickstart: a first deployment with the starter file
• Production: the settings to change before real traffic
• Command line: laidline init, serve, ingest and the rest
• HTTP API: the routes that server, admin, jobs and detect configure
• Licensing: the licence and issuer sections in context
• Third-party licences: the models and libraries Laidline runs