Configuration¶

All synthkit configuration is supplied via environment variables — either in a .env file (loaded from the working directory) or as process-level env vars that override the file. The .env.example at the repo root is the authoritative list of every variable synthkit reads.

The .env contract¶

install -m 600 .env.example .env
# fill values in-place, then:
docker compose up -d --wait     # or: ./synthkit

Keep comments on their own line. Docker Compose's env_file does NOT strip inline comments — TOKEN=abc123 # my token sets the variable to the literal string abc123 # my token. Put comments above the value, never beside it.

DRY_RUN defaults to true. A live push is always an explicit opt-in (DRY_RUN=false). This is a deliberate safety default: after explicitly selecting blueprints, you can inspect their full series inventory offline with no risk of pushing synthetic data.

Cross-references: for where to obtain the sink credentials see credentials.md; for self-observability tuning see self-observability.md; for Synthetic Monitoring setup see synthetic-monitoring.md; for Fleet Management setup see fleet-management.md.

Kubernetes state backend¶

STATE_BACKEND=file remains the default, including with HA_MODE=lease. File state keeps its existing paths and failure behavior. Optional STATE_BACKEND=kubernetes stores control state, boot manifest, git fetch status and fetched git YAML in named pre-created ConfigMaps. It uses in-cluster authentication only, never KUBECONFIG, discovery, create, list, watch or delete.

Each object owns binaryData["document"]; unrelated keys and metadata are preserved. Control and manifest documents have the same 768 KiB hard cap, and the total ConfigMap data must fit 1 MiB. Conflicts reload and replay the same request intent. Lost write responses are reconciled through atomic bounded operation receipts; an evicted/unreadable outcome fails closed with HTTP 503 state_outcome_unknown and failed persisted-state readiness. Conflict exhaustion is HTTP 409 state_conflict, not an in-memory success. Reset still clears source configuration and incidents; allocated source documents remain but no longer have authority.

Kubernetes-backed git snapshots boot offline without a git host or staged git files. A lease standby reads without writing; acquisition rereads documents and rebuilds/applies current state before production starts. CONFIG_SNAPSHOT_PATH is ignored for Kubernetes control state. BLUEPRINT_DATA_DIR is not authoritative for Kubernetes git/manifest state. With HA off, existing uploads remain file-backed in that directory: they still need retained local disk and do not follow a lease or gain shared-upload durability. HA uploads and automatic SM provisioning remain excluded. Manual diskless SM provisioning and acquisition-time activation are supported with the named SM mapping; file Lease HA still suppresses SM. The chart supports HA plus a Kubernetes-state SM Job with separate principals and Leases, using a matching engine image at least 1.6.0-rc.176. See Kubernetes for settings and explicit preview/apply/restart.

Synthetic data sinks¶

One Grafana Cloud Access Policy (CAP) token with metrics:write, logs:write, traces:write, and profiles:write covers all synthetic sinks. The GC_*_USER values are numeric data-source instance IDs, not email addresses.

Faro / RUM¶

RUM is disabled when either variable is empty.

Behaviour¶

SERIES_CAP and MAX_DPM_PER_SERIES protect different dimensions. SERIES_CAP truncates the number of series in an individual push after a construct emits it. MAX_DPM_PER_SERIES bounds how often each series may be sampled when a blueprint explicitly declares high_dpm.metric_interval. It does not make a blueprint high-DPM on its own. The per-blueprint series_budget is separate again: it is a fixed one-minute data-point allowance, so a 115-series blueprint at 6 DPM needs a budget of at least 690 to sustain every scheduled sample.

External / custom blueprint sources¶

These variables support pulling blueprints from git repositories or custom uploads via the control plane. See custom-blueprints.md for full usage.

Lease HA (binary staging mode)¶

HA_MODE unset, empty or off retains the single-emitter file workflow. lease uses client-go against one named, pre-created Lease and in-cluster credentials; it never creates, lists, watches or deletes Kubernetes resources. No kubeconfig fallback is used. File remains the default backend; optional Kubernetes document state is described above. Stateless HA chart wiring remains separate work, not enabled by these variables.

Startup rejects equality as well as overshoot: both the clamped retry series plus HTTP attempt plus margin, and the whole operation cap plus margin, must be strictly below HA_LEASE_DURATION - HA_RENEW_DEADLINE. The operation comparison includes the 2s state write deadline. OTLP's existing five-minute retry policy is included in this validation; Faro's many request waves and Sigil's sequential stages share the outer cap rather than restarting a deadline. A timeout without positive worker exit invokes terminal fencing and immediate exit.

Standby loads files and builds without starting producers, RUM sessions, Fleet lifecycle, git polling, state probes or source/manifest/SM artifact writes. Authenticated mutations return HTTP 503 not_leader before reading their bodies. Empty credential preflight and separately authenticated operational telemetry are the only standby export exceptions. Acquisition rereads control and fetched blueprint files, rebuilds topology, then commits load results/manifest and probes the file store through a private preparation capability. Only successful, uncancelled preparation opens public admission.

SIGTERM closes mutations and stops/joins producers first. All queues, admitted mutations, Fleet cleanup and HTTP shutdown share one SEND_DRAIN_DEADLINE (lease-mode default 10s when unset). An explicit value is validated, never silently clamped; a copied example with an explicit 30s still means 30s. Buffered delivery is best effort. Only positive sender/worker exit permits sealing renewal and explicitly clearing this process's Lease holder with a resourceVersion precondition. A cap expiry or leadership-loss callback crashes without drain, unregister, exporter flush or release. No work follows a release attempt. Operational providers have immutable ha.role=standby|leader resources; the one transition rotates providers without relabelling buffered standby events.

These are local admission fences, not distributed exclusivity. A request admitted before revocation may remain remotely in flight; arbitrary process suspension and delayed remote commits are not fenced. Handoff resets counters, histograms, RNG/shape state and queues; fixture identities remain deterministic. Unfinished traces/RUM sessions and buffered data can truncate. Crash takeover can cost the Lease duration plus polling and preparation, not universally seconds. File state is not shared failover continuity. HA upload mutations and automatic SM provisioning are unavailable. Kubernetes SM is explicitly provisioned under its own Lease and validated on emitter acquisition before production. File Lease HA still suppresses SM without artifact I/O.

Decoupled delivery queue¶

The delivery queue (internal/sink/queue) decouples construct rendering from network I/O, allowing constructs to run at their declared cadence regardless of sink latency. All five vars have safe defaults; tune only if you see backpressure warnings in self-observability or the operator UI.

Host bind (Docker Compose only)¶

These values are consumed by Docker Compose, not by the synthkit binary itself.

The committed default is a published image with the current healthcheck and rollback contract, not main or latest. Prefer the verified index digest. Never run raw docker compose config against a real credential file; just compose-check renders the deployment using .env.example as fake input. Selector assignments may be quoted or prefixed with export, matching Compose, but the deployment helper requires the selected value itself to be a direct literal image reference. Do not build it through interpolation from another environment variable.

Self-profiling (Pyroscope)¶

These variables configure continuous profiling of the synthkit process itself — not synthetic profile data sent to the target stack (see GC_PROFILES_URL above). This lane ships to a separate self-observability stack via its own credential triplet; it never uses GC_TOKEN. It follows SELFOBS_ENABLED and is independent of synthetic DRY_RUN.

AI generation ingest (optional)¶

The ai_agent workload's Sigil lane uses a separate credential triplet. All three values must be nonempty for this lane to be configured. Its absence does not disable that workload's traces or metrics.

Self-observability (OTLP)¶

RED metrics on the synthetic pipeline, Go runtime metrics, per-tick traces, and the operational log stream. Ships to a separate stack via its own credential triplet; never uses GC_TOKEN. Off by default; decoupled from DRY_RUN. See self-observability.md for the full signal catalogue and dashboard setup.

Synthetic Monitoring provisioner¶

These credentials authorize only the one-shot, version-matched sm-provision Compose job (or the same binary in a source checkout or a separately configured in-cluster Job). The emitter uses their presence to bind and validate its snapshot, but it never calls the SM API: provisioning, registration persistence, and the required emitter restart remain separate phases. First v2 format activation requires explicit apply/restart; subsequent unchanged-spec/target/schema release bumps retain registration, while the tool must still match the current snapshot version. See synthetic-monitoring.md.

Fleet Management¶

Container runtime hint¶