Skip to main content
The server, control plane, and worker read configuration from environment variables. A deployment must give all three the same datastore, event bus, and secret-provider settings. The Helm chart renders these variables from chart values; other platforms set them directly. This page does not cover the filament CLI, which uses a YAML configuration file.

​
Shared configuration

The server, control plane, and worker read the variables in this section.

​
Datastore

Use PostgreSQL for a split deployment. The service binaries accept SQLite, but a local SQLite file is not a shared datastore for services running on different hosts.

​
Event bus

DISPATCH_MODE=inproc changes where runs execute; it does not replace the event bus.

​
Secret provider

The datastore-backed provider stores AES-GCM encrypted values in PostgreSQL or SQLite. Every service must receive the same encryption key.
Keep ENCRYPTION_KEY safe and stable. Changing it makes existing secrets unreadable. ENCRYPTION_KEY_ID records an identifier, but it does not provide a multi-key rotation mechanism.
The AWS provider loads credentials through the standard AWS SDK chain. It stores each Filament secret as a JSON envelope in AWS Secrets Manager.

​
Logs and OpenTelemetry

Filament enables OpenTelemetry export when any OTLP endpoint is set. It creates both metrics and trace exporters using the selected protocol. The exporters also honor the standard OTLP headers, TLS, timeout, and compression variables for that transport. Application logs remain JSON on standard output; Filament does not export logs through OTLP.

​
Server

​
Authentication

When AUTH_PROVIDER is unset, the API and web application are unauthenticated.
Only the server reads authentication variables.

​
Control plane

Run exactly one control-plane replica. Multiple replicas may race while coordinating schedules and runs.
In kubernetes mode, the control plane creates a worker Job for each run and uses the reaper to detect workers that stop reporting heartbeats. In inproc mode, runs execute inside the control-plane process. There are no worker Jobs, heartbeats, or reaper.

​
Kubernetes dispatch

These variables apply only when DISPATCH_MODE=kubernetes. The Helm chart sets them from its controlPlane.dispatch values.

​
Worker

The Kubernetes dispatcher injects TENANT_ID and RUN_ID. The worker loads the remaining shared settings from its Secret and ConfigMap. Invalid or non-positive HEARTBEAT_SECONDS values use the 30-second default.

​
Standalone

Standalone is intended for testing and evaluation. It has its own embedded NATS server, SQLite datastore, and read-only environment secret provider. Standalone also reads LOG_LEVEL and NATS_TTL_SECONDS. Its secret provider maps a reference such as postgres-creds/dsn to POSTGRES_CREDS_DSN. It cannot create, update, or delete secrets. The public Go API also uses INGESTION_ADDR. See Embedded for library configuration.

​
Migrations

PostgreSQL migrations are embedded in the server image. The server’s -migrate flag waits up to five minutes for the database, applies pending migrations, and exits:
The Helm chart runs this command in a post-install and post-upgrade hook. Use the same command as a pre-deploy step on platforms such as Railway. SQLite applies its migrations when the datastore opens. The Helm chart README lists the chart values that produce these variables.