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.

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.

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.

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). The emitter uses their presence to bind and validate its private snapshot, but it never calls the SM API: provisioning, registration persistence, and the required emitter restart remain separate phases. See synthetic-monitoring.md.

Fleet Management¶

Container runtime hint¶