Reference

Environment Variables

Every environment variable OKE reads — connection URLs, driver overrides, secrets, and CLI flags.

OKE reads environment variables at boot for connection detail and secrets — never for behavior you could declare in oke.config.ts. Under oke dev, Compose writes these into .env.local; this page is the full map.

The one rule

Put drivers, images, and locale lists in oke.config.ts. Use env vars for URLs, credentials, and runtime posture the host injects — not for inventing new behavior.

Smallest Example

Let Compose write the map

oke dev

Compose fills .env.local with DATABASE_URL, Redis, S3, and vault keys for the pinned images.

Override one URL when needed

export DATABASE_URL=postgres://user:pass@db:5432/oke

Conventional names win over OKE_* aliases, then built-in defaults.

Precedence

Resolution order

For anything with both an OKE_* variable and a conventional one (like DATABASE_URL), the conventional variable wins first, then the OKE_* form, then the built-in default.

SQL store

VariableUsed forDefault when unset
DATABASE_URLPostgres connection (postgres store / clock / journal / Console operator plane, drizzle-kit). App tables stay in public; Console operators/sessions use schema oke_console on the same database. When PgDog is pinned, this points at the pooler (:6432).postgres://localhost:5432/oke
OKE_STORE_SQL_URLDirect SQL URL (Postgres host, even when PgDog fronts the app). Also used by Console when DATABASE_URL is unset.—
OKE_PGDOG_URLPgDog pooler URL (same value as DATABASE_URL when both are present)—
OKE_PGLITE_URLPGlite data dir or memory:// (pglite driver; required for store.sql.test)memory:// in test; else .oke/pgdata
OKE_SQL_DRIVERForce the sql driver id at bootconfig map

oke test sets OKE_PGLITE_URL=memory:// when unset. The sqlite driver and OKE_SQLITE_URL are removed.

Index store

VariableUsed forDefault when unset
OKE_INDEX_DRIVERForce the index driver idconfig map
OKE_STORE_INDEX_URLMeilisearch base URL (meilisearch driver)—
OKE_STORE_INDEX_KEYMeilisearch API / master key (meilisearch driver)MEILI_MASTER_KEY

KV store

VariableUsed forDefault when unset
REDIS_URLCache Redis connectiondriver default
OKE_STORE_KV_URLExplicit cache KV URL override—
OKE_KV_DRIVERForce the kv driver idconfig map

Files store

VariableUsed forDefault when unset
S3_BUCKETBucket name (s3 driver)—
S3_ENDPOINTS3-compatible endpoint (RustFS)—
S3_ACCESS_KEY_IDAccess key—
S3_SECRET_ACCESS_KEYSecret key—
S3_REGIONRegion—
S3_SESSION_TOKENSession token (temporary creds)—
OKE_STORE_FILES_DBExplicit files location override—
OKE_FILES_DRIVERForce the files driver idconfig map

Vault

Built-in store uses OKE_VAULT_MASTER_KEY (or --key / stdin on CLI). Managed providers use the vars below — see Vault for which each id needs.

VariableUsed forDefault when unset
OKE_VAULT_PROVIDERManaged backend (aws-secrets-manager · azure-key-vault · gcp-secret-manager · doppler · 1password)— (platform-injected)
OKE_VAULT_REGIONCloud region (AWS Secrets Manager; GCP user-managed replication)—
OKE_VAULT_MOUNTScope: AWS/Azure prefix, GCP project[/prefix], Doppler project/config, 1Password vault name—
OKE_VAULT_MASTER_KEYBuilt-in vault master key (base64)—
OKE_VAULT_URLAzure Key Vault URI, 1Password Connect host, optional Doppler origin—
OKE_VAULT_TOKENDoppler service/personal token, 1Password Connect token—

Channel (email) — boot binder

Read when drivers.channel.email resolves to that driver id.

VariableUsed for
SMTP_URLsmtp — full SMTP URL (smtp://…)
SMTP_USEROverrides the user embedded in SMTP_URL
SMTP_PASSWORDOverrides the password in SMTP_URL
OKE_CHANNEL_EMAIL_URLAlternative to SMTP_URL
RESEND_API_KEYresend API key
SNDR_API_KEYsndr API key
SNDR_BASE_URLOptional SNDR API origin (default api.sndr.sh)
TAQNYAT_MAIL_TOKENtaqnyat-mail bearer token (Email-enabled)
TAQNYAT_CAMPAIGNtaqnyat-mail campaign name

Channel (SMS) — boot binder

Read when drivers.channel.sms resolves to that driver id (console opens nothing).

VariableUsed for
TAQNYAT_BEARER_TOKENtaqnyat bearer token
TAQNYAT_TOKENAlias for TAQNYAT_BEARER_TOKEN
TAQNYAT_SENDERTaqnyat pre-approved sender id
MSEGAT_USERNAMEmsegat account username
MSEGAT_API_KEYmsegat API key
MSEGAT_SENDERMsegat pre-approved sender id
UNIFONIC_APPSIDunifonic AppSid
UNIFONIC_APP_SIDAlias for UNIFONIC_APPSID
UNIFONIC_SENDERUnifonic SenderID (optional)

WhatsApp (wa-cloud) and push (webpush / fcm) are not opened from env at boot — pass them on BootOptions.channel.drivers with their open options.

Live test gates (opt-in, contributors)

Provider-quota-burning live suites in the okengine repo are double-gated: the medium flag plus that provider's real credentials — credentials alone never send. App projects can ignore these.

VariableUsed for
OKE_SMS_LIVE=1 allows live SMS provider tests (e.g. Taqnyat OTP)
OKE_EMAIL_LIVE=1 allows live email provider tests (e.g. Taqnyat Mail)

AI providers

VariableUsed forDefault when unset
ANTHROPIC_API_KEYanthropic driver credential—
ANTHROPIC_MODELModel override for the anthropic driver—
OPENAI_API_KEYopenai-compatible driver credential—
OPENAI_BASE_URLopenai-compatible base URLOpenAI cloud
OKE_AI_DRIVERForce the AI driver id (honoured under Compose / oke dev)config map
OKE_AI_URLopenai-compatible base URL (must end in /v1) — BYO; Compose does not manage inference—
OKE_AI_MODELDefault model id for openai-compatible / setup bindings—
OKE_AI_VISION_MODELVision model id written by oke ai setup (logical ai.model("vision"))—
OKE_AI_EMBED_MODELEmbedding model id written by oke ai setup—

Framework behavior

VariableUsed for
OKE_DOCKER"1" marks Compose / oke dev posture (set by the CLI)
OKE_DB_AUTO_PUSHOverrides db.autoPush at boot
OKE_DRIZZLE_DIALECT"postgresql" for drizzle-kit overlays (templates hardcode it)
OKE_DEV_REQUEST_LOG"1" logs requests during oke dev (set by the CLI) — surface, flow, status, timestamp, run id
OKE_CONSOLE_SECRETConsole operator-session signing secret (HMAC) — set in production; else .oke/console.secret. Not a Vault contract.
OKE_CONSOLE_AUTH_STORE"1" lists the operator-plane oke_console schema in Store browse (read-only). Hidden by default.
OKE_RUNS_INGEST_URLHost → Console WideEvent ingest URL (oke dev sets this on the app child). Enables a memory runs store + push.
OKE_RUNS_INGEST_SECRETShared secret for POST /console/runs/ingest (x-oke-runs-ingest header). Minted by oke dev; never return events.
PORTApp port in production containers (default 6530)
NODE_ENV"production" switches the Console to its production posture

Console operator rows are not stored in .oke/console.sqlite. With DATABASE_URL (or OKE_STORE_SQL_URL) they live in Postgres schema oke_console. Without a Postgres URL, Console uses PGlite under .oke/console-pg for local reopen durability.

Troubleshooting

Learn more

  • Configuration — the declarative side of the same knobs
  • Vault — how OKE_VAULT_* gets minted on first boot
  • CLI — which commands write these for you
  • Security — OKE_CONSOLE_SECRET

Next

Configuration

Drivers and images in oke.config.ts.

CLI

oke dev writes the env map.

Vault

Master key and managed providers.

Configuration

Every option in oke.config.ts — three environments (dev · test · prod), drivers, images, i18n, tenancy, privacy, db sync, topology, ports, and console.

fx

The complete fx surface — every call a Flow can make, its signature, and the effect it records.

On this page

Smallest ExampleLet Compose write the mapOverride one URL when neededPrecedenceSQL storeIndex storeKV storeFiles storeVaultChannel (email) — boot binderChannel (SMS) — boot binderLive test gates (opt-in, contributors)AI providersFramework behaviorTroubleshootingLearn moreNext