Skip to Content
LYNKORIADocs

Environment variables

Every environment variable, grouped by the application that reads it, with examples, sources and production requirements.

Reviewed 2026-11-13 against apps/api/src/config.ts, apps/scanner/src/app.ts, the Vite configs, scripts and infrastructure templates. Values below are placeholders; never put real secrets in documentation, Git, images or logs.

apps/api/src/config.ts validates the API's variables at startup and reports names only, never values. With NODE_ENV=production it also refuses non-TLS URLs, a missing database CA, a missing scanner (when storage is configured), provider mocks and ADMIN_DEV_EMAIL. Use NODE_ENV=production for staging too; LYNKORIA_ENVIRONMENT says which environment it is.

Where the values live: .env.example is the local template (copy to .env, gitignored). In staging and production, OpenTofu sets every API variable on App Platform (infra/opentofu/platform/app.tf): generated secrets come from secrets.tf and the zone stack, connection strings from the managed databases, and account-specific values from GitHub environment variables (step 4). Nothing is filled in by hand.

Generate secrets with: openssl rand -base64 32 (32-byte secrets), openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 (messaging key), or pnpm --filter @lynkoria/api exec tsx scripts/gen-secrets.ts (local development only).

API (apps/api)

Runtime and network

NameRequiredDescriptionExampleSourceProduction requirement
NODE_ENVNo (development)development, test or production; production enables the strict checks aboveproductionDeploymentproduction in staging and production
LYNKORIA_ENVIRONMENTNo (staging)Which environment this deployment serves; keys/environments of the other kind are rejectedproductionDeploymentMatches the deployment; lynk_live_ keys only work with production
PORTNo (3001)HTTP and Socket.IO port8080PlatformApp Platform http_port
METRICS_PORTNo (9464)Prometheus metrics listener9464PlatformInternal port only; never routed publicly
LOG_LEVELNo (info)pino levelinfoOperatorinfo or warn; logs redact tokens and secrets at any level
PUBLIC_API_ORIGINNo (http://localhost:3001)Public API origin (OpenAPI servers, links)https://api.example.comDNSHTTPS
CONSOLE_ORIGINProductionExact console origin for CORS and the cross-origin mutation checkhttps://console.example.comDNSHTTPS, required
ALLOWED_ORIGINSNo (empty)Comma-separated exact browser origins for sockets and CORS; each project also has its own listhttps://app.example.comProduct teamsExact HTTPS origins only, no wildcards
WEBHOOK_ALLOWED_ORIGINSNo (empty)Operator-approved product webhook origins; empty disables production webhook deliveryhttps://hooks.example.comProduct teamsHTTPS only; the worker re-checks and never follows redirects
TRUST_PROXYNo (false)Read the client IP from CLIENT_IP_HEADER instead of the socket addresstrueDeploymenttrue only behind an ingress that overwrites that header
CLIENT_IP_HEADERNo (do-connecting-ip)The one header the trusted ingress sets; x-forwarded-for uses its last entrycf-connecting-ipIngress documentationdo-connecting-ip on App Platform; cf-connecting-ip behind Cloudflare
CF_ORIGIN_SECRETWith cf-connecting-ipOrigin lock: every route except /health/*, and socket upgrades, need header x-lynkoria-origin-secret with this value48 random bytes, base64Cloudflare Transform Rule32+ characters; required in production when CLIENT_IP_HEADER=cf-connecting-ip

Database and Redis

NameRequiredDescriptionExampleSourceProduction requirement
DATABASE_URLYesPooled connection as the runtime rolepostgresql://lynkoria_app:…@pool-host:25061/lynkoriaManaged PostgreSQL poolPrivate endpoint; runtime role (no DDL)
DATABASE_URL_DIRECTProductionDirect runtime-role session for LISTEN (the pooler cannot hold it)postgresql://lynkoria_app:…@db-host:25060/lynkoriaManaged PostgreSQLRequired; never the migration role
DATABASE_CA_CERTProductionPEM CA; enables verified TLS (URL sslmode is ignored when set)CA certificate PEM textProvider "Download CA"Required; literal \n escapes accepted
DATABASE_POOL_MAXNo (10)Pool size per API instance10Capacity planningBelow the pooler's per-user limit
REDIS_URLYesRedis/Valkey for presence leases, rate limits and worker locksrediss://default:…@valkey-host:25061Managed Valkeyrediss:// (TLS, verified)

LiveKit

NameRequiredDescriptionExampleSourceProduction requirement
LIVEKIT_URLYesClient signaling URL returned with every join tokenwss://rtc.example.comMedia DNSwss://
LIVEKIT_API_URLNoServer API URL; defaults to LIVEKIT_URL with http(s)https://rtc.example.comMedia DNSHTTPS if set
LIVEKIT_KEYS_JSONYesKey reference → {apiKey, apiSecret}; environments pick a reference in the console{"prod-vibelynk":{"apiKey":"API…","apiSecret":"…"}}LiveKit keys: you generateOne key per project environment; secrets ≥32 characters
LIVEKIT_WEBHOOK_KEYYesKey id LiveKit signs webhooks withlk_platform_webhookLiveKit webhook.api_keyDedicated to webhooks
LIVEKIT_WEBHOOK_SECRETYesMatching secret (≥32 characters)32+ random charactersGenerated, mirrored in LiveKitSecret manager

Secrets and tokens

NameRequiredDescriptionExampleSourceProduction requirement
SERVICE_KEY_PEPPERYesHMAC pepper for service-key digests (≥32 bytes, base64)output of openssl rand -base64 32GeneratedChanging it invalidates every service key
WEBHOOK_SECRET_MASTERYesMaster for derived product webhook secrets (≥32 bytes, base64)output of openssl rand -base64 32GeneratedMust differ from the pepper; changing it rotates every webhook secret
MESSAGING_JWT_PRIVATE_KEYYesES256 (P-256) PKCS8 key that signs messaging tokensPKCS8 PEM textopenssl genpkeySecret manager; escaped newlines accepted
MESSAGING_JWT_KIDYesKey id for the current signing keymsg-2026-11OperatorUnique per key
MESSAGING_JWT_PREVIOUS_KEYS_JSONNo ({})Retired kid → public PEM, accepted until their tokens expire{"msg-2026-10":"<public key PEM>"}Previous keyKeep at least one token TTL (10 min) after rotation, then remove

Console

NameRequiredDescriptionExampleSourceProduction requirement
CF_ACCESS_TEAM_DOMAINNoCloudflare Access team; when set with CF_ACCESS_AUD, every console request also needs a matching Access identityteam.cloudflareaccess.comCloudflare Zero TrustBoth or neither; recommended as defense in depth
CF_ACCESS_AUDNoAccess application audience tag64-hex audienceCloudflare Zero TrustBoth or neither
ADMIN_DEV_EMAILNoLocal only: treat every console request as this userdev@example.comDeveloperRefused in production
CONSOLE_LOGIN_RATE_LIMITNo (20)Sign-in attempts per client IP per minute (each email is also capped at 10)20OperatorDepends on a trustworthy CLIENT_IP_HEADER

Object storage and recording

NameRequiredDescriptionExampleSourceProduction requirement
SPACES_REGIONNo (sgp1)S3 regionsgp1ProviderMatches the bucket
SPACES_ENDPOINTWith storageS3 endpointhttps://sgp1.digitaloceanspaces.comProviderHTTPS; all four storage variables or none
SPACES_BUCKETWith storagePrivate bucket for attachments and recordingslynkoria-prod-attachmentsBucket you createPrivate, CORS and lifecycle applied
SPACES_ACCESS_KEY_IDWith storageAccess keyDO00…Spaces key (not an API token)Scoped to the bucket where supported
SPACES_SECRET_ACCESS_KEYWith storageSecret key(secret)Spaces keySecret manager
SPACES_FORCE_PATH_STYLENo (false)Path-style addressing for local S3-compatible storestrueLocal onlyfalse
EGRESS_S3_ENDPOINTNoStorage endpoint as reachable from Egress, if differenthttps://sgp1.digitaloceanspaces.comEgress networkOnly when Egress uses another route
RECORDING_RETENTION_DAYSNo (30)Finished recordings and files are deleted after this many days30Product/legal decisionAgree per product (ADR 009)

Malware scanning

NameRequiredDescriptionExampleSourceProduction requirement
SCANNER_URLProduction with storagePrivate scanner endpointhttps://10.104.0.5:3344Scanner hostVPC-private address; https: unless the scanner is on the same host
SCANNER_TOKENWith SCANNER_URLThis API's consumer token (≥32 characters)(secret)Same value as in SCANNER_TOKENS_JSONSecret manager; rotate by listing the new token next to the old one on the scanner first
SCANNER_CA_CERTWith an https: scanner on a private CAPEM of the CA that issued the scanner certificate; the only CA trusted for the scannerCA PEMOpenTofu (secrets.tf); scripts/scanner-pki.sh locallyLiteral \n escapes accepted; concatenate old and new during a CA rotation (ADR 023)
ATTACHMENT_SCANNINGNo (required)required or disabledrequiredOperatordisabled only with a recorded decision; attachments are then unscanned

Push notifications

NameRequiredDescriptionExampleSourceProduction requirement
PUSH_CREDENTIALS_JSONNo ({})Credential reference → {fcm?, apns?}; environments reference one{"vibelynk":{"fcm":{"projectId":"…","clientEmail":"…","privateKey":"…"}}}Firebase service account, APNs .p8 keySecret manager; one entry per product
PUSH_FCM_BASE_URLNoTest mock for FCMhttp://127.0.0.1:9100TestsRefused in production
PUSH_FCM_TOKEN_URLNoTest mock for the Google OAuth token endpointhttp://127.0.0.1:9100/tokenTestsRefused in production
PUSH_APNS_BASE_URLNoTest mock for APNshttps://127.0.0.1:9101TestsRefused in production

Limits, workers and observability

NameRequiredDescriptionExampleSourceProduction requirement
MAX_MESSAGE_BYTESNo (16384)Maximum message body size16384Operator
MESSAGE_RATE_LIMITNo (120)Messages per user per minute120Operator
SERVICE_RATE_LIMITNo (6000)Requests per service key per minute6000Operator
SHUTDOWN_DRAIN_SECONDSNo (0)Seconds /health/ready reports draining before connections close on SIGTERMunset on App Platform (its termination.drain_seconds drains first); 5–15 behind other ingressesOperatorKeep below the platform's kill timeout minus 15 s
WORKERS_ENABLEDNo (true)Outbox, push delivery, retention, usage and reconciliation workerstrueOperatorKeep true on every instance (ticks coordinate through Redis locks)
OTEL_EXPORTER_OTLP_ENDPOINTNoOTLP trace collector; tracing is off when unsethttp://otel-collector:4318MonitoringCollector on the private network
OTEL_SERVICE_NAMENo (lynkoria-api)Service name on traceslynkoria-apiMonitoring

Malware scanner (apps/scanner)

NameRequiredDescriptionExampleSourceProduction requirement
SCANNER_TOKENS_JSONYesConsumer → bearer token (≥32 characters each){"lynkoria-api":"…","fidescript":"…"}GeneratedOne token per consumer, or a list of up to 4 during rotation ({"lynkoria-api":["new…","old…"]})
PORTNo (3344)Listener3344ComposeBound to the private interface (SCANNER_BIND)
LOG_LEVELNo (info)pino levelinfoOperator
CLAMD_HOST / CLAMD_PORTNo (127.0.0.1/3310)clamd INSTREAM endpointclamd / 3310ComposeInternal network only
SCANNER_MAX_BYTESNo (50 MiB)Largest accepted file52428800Operator≥ the largest project attachment limit
SCANNER_TIMEOUT_MSNo (30000)Per-scan timeout30000Operator
SCANNER_MAX_CONCURRENCYNo (4)Concurrent scans; excess requests get 4294CapacitySize to clamd CPU and memory
SCANNER_MAX_SIGNATURE_AGE_HOURSNo (48)Refuse to scan with older signatures (fail closed)48Operator
SCANNER_ARCHIVE_MAX_UNCOMPRESSEDNo (200 MiB)ZIP/GZIP total uncompressed size limit209715200Operator
SCANNER_ARCHIVE_MAX_ENTRIESNo (5000)ZIP entry limit5000Operator
SCANNER_ARCHIVE_MAX_RATIONo (100)Compression-ratio limit100Operator
SCANNER_TLS_CERT_FILE / SCANNER_TLS_KEY_FILEBoth or neitherServe HTTPS (TLS 1.3) with this certificate and key; reloaded on SIGHUP/tls/tls.crt / /tls/tls.keyOpenTofu cloud-init; scripts/scanner-pki.sh locallyRequired by infra/scanner/compose.yaml

infra/scanner/compose.yaml also reads SCANNER_IMAGE (image reference), SCANNER_BIND (private IP to publish on) and SCANNER_TLS_DIR (directory with tls.crt, tls.key and ca.crt).

Console build (apps/admin)

NameRequiredDescriptionExampleProduction requirement
VITE_API_ORIGINProductionAPI origin compiled into the console (public value)https://api.example.comMatches PUBLIC_API_ORIGIN; add it to the console CSP
VITE_DOCS_URLNoDocumentation link in the sidebar; hidden when unset in buildshttps://lynkoria.com/docs
LYNKORIA_API_PROXYNoDev server only: where /v1 is proxiedhttp://127.0.0.1:3011Not used in builds

Playground (apps/playground, development only)

NameRequiredDescriptionExample
PLAYGROUND_SERVICE_KEYFor the demoStaging service key used by the dev-server demo backend; never in a buildlynk_test_… from pnpm db:seed
VITE_API_ORIGINNoAPI origin for the browserhttp://localhost:3001

Landing page and documentation (apps/docs)

NameRequiredDescriptionExampleProduction requirement
NEXT_PUBLIC_SITE_URLNoPublic origin for canonical URLs, sitemap.xml and robots.txt (build time)https://lynkoria.comDefaults to https://lynkoria.com; set the staging origin for staging builds

Local infrastructure (infra/local/compose.yaml)

LYNKORIA_PG_PORT, LYNKORIA_REDIS_PORT, LYNKORIA_VALKEY_PORT and LYNKORIA_CLAMD_PORT override host ports when the defaults collide with other services; update DATABASE_URL/REDIS_URL to match.

Scripts and tooling

NameUsed byDescription
SEED_OWNER_EMAILdist/bootstrap.js, pnpm db:seedFirst console owner (seed falls back to ADMIN_DEV_EMAIL)
MIGRATIONS_DIRdist/migrate.jsOverride the migrations folder (defaults to the bundled drizzle/)
SEED_LIVEKIT_KEY_REFpnpm db:seedLiveKit key reference for sample products
TOFU_STATE_BUCKET, SPACES_ACCESS_KEY_ID, SPACES_SECRET_ACCESS_KEY, DIGITALOCEAN_ACCESS_TOKEN, CLOUDFLARE_API_TOKEN, TF_VAR_*infra/opentofu/run.sh, .github/workflows/deploy.yml, infra.ymlOpenTofu backend, provider credentials and stack variables; the full list is in step 4
PUBLIC_API_ORIGIN, LYNKORIA_SERVICE_KEYscripts/verify-production.mjsDeployed API and a disposable scoped key
BASE_URL, SERVICE_KEY, VUS, DURATION, RATE, RECEIVERS, MESSAGES, RUN_IDloadtest/, apps/api/scripts/load-messaging.tsLoad-test targets and shape
LK_URL, LK_KEY, LK_SECRET, LK_CONTAINER, LK_NETWORK, STEPS, RESloadtest/livekit/run.shLiveKit load-test inputs
I_HAVE_PRODUCTION_AUTHORIZATIONLoad testsMust be yes to target a lynkoria.com host; get written authorization first
S3_TEST_ENDPOINT, S3_TEST_ACCESS_KEY, S3_TEST_SECRET_KEY, SCANNER_TEST_CLAMD, TEST_LOG_LEVEL, LIVEKIT_API_KEY, LIVEKIT_API_SECRETAPI testsTest infrastructure overrides; tests always use a _test database

Consistency notes

  • Project features, quotas, origins and retention are database settings managed in the console, not environment variables.
  • CLIENT_IP_HEADER is set to cf-connecting-ip in infra/opentofu/platform/app.tf, since the API is proxied; CF_ORIGIN_SECRET comes from the zone stack.
  • The migration job gets its own DATABASE_URL_DIRECT (the lynkoria_migrate role); the API service never receives migration credentials.
  • GitHub Actions secrets and variables for deployment are listed in step 4.

On this page