Configuration

All configuration is via environment variables in the repo-root .env (the API loads it from the project root). Copy from .env.example to get started.

Required

Variable	Description	Example
DATABASE_URL	PostgreSQL connection string	postgres://postgres:postgres@localhost:5432/postgres

That’s it. Everything else is optional — Truss works with just a database.

API Server

Variable	Description	Default
API_PORT	Port the Express server listens on	8787
QUERY_TIMEOUT_MS	Max query execution time (ms)	10000
SQL_MAX_ROWS	Max rows returned by the SQL workbench	200

Authentication (Ory Kratos)

Required for user authentication. Without these, the dashboard runs in dev mode (no login required).

Variable	Description	Default
KRATOS_PUBLIC_URL	Kratos public API	http://localhost:4433
KRATOS_ADMIN_URL	Kratos admin API	http://localhost:4434
KRATOS_ADMIN_TOKEN	Bearer token for the Kratos admin proxy	(none)
KRATOS_IDENTITY_SCHEMA_ID	Identity schema to use for new users	default
KRATOS_OIDC_PROVIDERS	Comma-separated social login provider IDs	(none)
TRUSS_AUTH_REQUIRED	Require authentication for dashboard. Set false for local dev to skip login. Production (NODE_ENV=production) always forces auth on regardless of this value.	true
TRUSS_ADMIN_IDENTITY_IDS	Comma-separated Kratos identity UUIDs for admin access	(none)
TRUSS_BOOTSTRAP_ADMIN	Seed a default admin on first boot (set false to disable)	true
TRUSS_BOOTSTRAP_ADMIN_EMAIL	Email for the seeded first-boot admin	admin@truss.local
TRUSS_BOOTSTRAP_ADMIN_PASSWORD	Password for the seeded admin (blank = a random one is generated and printed to the API logs)	(none; blank → a random password is generated and logged)
TRUSS_DEMO_MODE	Enable anonymous read-only demo access via the X-Demo: true header (rate-limited, mutations blocked). Security-relevant — leave off unless you intend a public demo.	false

First-boot admin

When Kratos is configured and TRUSS_BOOTSTRAP_ADMIN is not false, Truss seeds a default admin on startup so you can log in immediately, the same way Grafana and Argo CD do. This only ever runs when no identity exists yet, so it never overwrites real users.

• Email: admin@truss.local (override with TRUSS_BOOTSTRAP_ADMIN_EMAIL).

• Password: if you set TRUSS_BOOTSTRAP_ADMIN_PASSWORD, that value is used. If you leave it blank, a random password is generated and printed once to the API logs:

  # Docker Compose
  docker compose logs truss-api | grep "Default admin"
  # Kubernetes / Helm
  kubectl -n truss logs deploy/truss-api | grep "Default admin"

The seeded account has full admin rights. Change the password right after your first login in the dashboard under Settings → Account → Change Password (which runs the Ory Kratos self-service settings flow). To opt out of seeding entirely, set TRUSS_BOOTSTRAP_ADMIN=false and create your first user via the normal registration screen.

Authorization (Ory Keto)

Required for relation-based access control (ReBAC).

Variable	Description	Default
KETO_READ_URL	Keto read API	http://localhost:4466
KETO_WRITE_URL	Keto write API	http://localhost:4467
KETO_ADMIN_TOKEN	Bearer token for the Keto admin proxy	(none)

OAuth2 / OIDC (Ory Hydra)

Required for OAuth2 client management and token issuance.

Variable	Description	Default
HYDRA_PUBLIC_URL	Hydra public API (OAuth2 endpoints)	http://localhost:4444
HYDRA_ADMIN_URL	Hydra admin API (client management)	http://localhost:4445
HYDRA_ADMIN_TOKEN	Bearer token for the Hydra admin proxy	(none)

API Gateway (Ory Oathkeeper)

Required for the API gateway / reverse proxy features.

Variable	Description	Default
OATHKEEPER_PROXY_URL	Oathkeeper proxy endpoint	http://localhost:4455
OATHKEEPER_ADMIN_URL	Oathkeeper admin API	http://localhost:4456
OATHKEEPER_ADMIN_TOKEN	Bearer token for the Oathkeeper admin proxy	(none)

Storage (MinIO / S3)

Required for file storage features.

Variable	Description	Default
MINIO_S3_ENDPOINT	S3-compatible endpoint URL	http://localhost:9000
MINIO_CONSOLE_URL	MinIO web console URL	http://localhost:9001
MINIO_ACCESS_KEY	S3 access key	minioadmin
MINIO_SECRET_KEY	S3 secret key	minioadmin
MINIO_REGION	S3 region	us-east-1
MINIO_FORCE_PATH_STYLE	Use path-style S3 URLs (required for MinIO)	true

Cache / KV (Valkey)

Optional. Powers the Cache / KV panel (keyspace browser, stats, developer views). Valkey is Redis-compatible, so an existing Redis also works. Without these, the Cache panel reports “not configured” and the rest of Truss runs normally.

Variable	Description	Default
VALKEY_HOST	Valkey/Redis hostname	localhost
VALKEY_PORT	Valkey/Redis port	6379
VALKEY_PASSWORD	requirepass value (blank = no auth)	(none)
VALKEY_URL	Full redis:// URL, overrides host/port/password	(none)

VALKEY_PASSWORD is the cache service’s own auth and is unrelated to the dashboard login. The bundled Compose and Helm setups generate it for you.

Observability

Metrics (/metrics) and structured JSON logs are always on. Tracing is opt-in. See the Observability guide for the full setup.

Variable	Description	Default
OTEL_EXPORTER_OTLP_ENDPOINT	OTLP/HTTP endpoint for trace export (e.g. http://collector:4318). Unset = tracing off.	(none)
OTEL_SERVICE_NAME	Service name attached to spans	truss-api
LOG_LEVEL	pino log level (debug/info/warn/error)	info

Cross-Origin

Variable	Description	Default
CORS_ALLOWED_ORIGINS	Comma-separated frontend origins	(none)
TRUSS_PUBLIC_URL	Public URL users hit in the browser (used to infer the session-cookie Secure flag)	http://localhost:3000
COOKIE_SECURE	Force the session-cookie Secure flag (true/false). Inferred from the URL scheme when unset	(inferred)

The session cookie is only marked Secure when you serve Truss over HTTPS. Serving over plain HTTP (e.g. http://localhost:3000) keeps it non-Secure so the browser does not drop it; otherwise login would never stick. Set COOKIE_SECURE=true to force it on behind an HTTPS-terminating proxy that the API can’t detect.

When deploying the dashboard and API on different domains, set this to allow cross-origin requests:

CORS_ALLOWED_ORIGINS=https://app.yourdomain.com,https://truss.yourdomain.com