Configuration
Every variable below is read somewhere in the codebase. Anything not listed here is not read by Orchka.
Orchka runs as two processes — the Next.js web app and the BullMQ worker —
and they need different variables. Locally both read apps/web/.env.local; the
worker loads it explicitly, so one file serves both.
Required
These three are validated at boot. A missing or malformed value stops the process starting rather than failing later, mid-run.
| Variable | Processes | Notes |
|---|---|---|
DATABASE_URL | web, worker | PostgreSQL connection string |
REDIS_URL | web, worker | redis:// or rediss://. The scheme is honoured — rediss:// enables TLS. A URL with no port defaults to 6379; a /N path selects the database |
CREDENTIAL_ENCRYPTION_KEY | web, worker | Exactly 64 hex characters (openssl rand -hex 32). Must be byte-identical across both processes — a mismatch does not error, it makes stored credentials undecryptable. Back it up; there is no recovery or rotation path |
Authentication
| Variable | Process | Notes |
|---|---|---|
BETTER_AUTH_SECRET | web | Signs sessions. better-auth refuses to start in production if it is missing or left at the default |
BETTER_AUTH_URL | web | Your public URL. Used to build links in emails and OAuth callbacks |
GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET | web | Optional — enables GitHub sign-in |
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET | web | Optional — enables Google sign-in |
Used for password reset and address confirmation.
| Variable | Process | Notes |
|---|---|---|
RESEND_API_KEY | web | Optional. Without it nothing is sent — the message and its link are written to the server log instead, so the flow is testable locally. Set it before anyone but you can sign up |
EMAIL_FROM | web | Sender address. Defaults to Orchka <onboarding@resend.dev> |
Access control
| Variable | Process | Notes |
|---|---|---|
ORCHKA_ADMIN_EMAILS | web | Comma-separated addresses allowed to reach /settings/engine and the queue stats. Matched case-insensitively. Deny-all when unset — including for you |
Keyed on email rather than user id on purpose: an id is generated at sign-up and cannot be known at deploy time.
Execution
| Variable | Process | Default | Notes |
|---|---|---|---|
ORCHKA_PARALLEL_BRANCHES | worker | off | 1 runs independent branches concurrently instead of one at a time. See Execution Reliability |
ORCHKA_ALLOW_PRIVATE_NETWORK | worker | off | 1 lets HTTP nodes and agent tools reach private, loopback and link-local addresses. Off by default — see Security |
ORCHKA_STEP_STREAMS | worker | on | 0 falls back to the legacy Redis list for step history instead of a stream |
Retention
The worker runs one sweep daily. See Operations.
| Variable | Process | Default | Notes |
|---|---|---|---|
ORCHKA_RETAIN_STEPS_DAYS | worker | 30 | Age at which step detail and payloads are deleted |
ORCHKA_RETAIN_EXECUTIONS_DAYS | worker | 90 | Age at which execution rows themselves are deleted |
Runtime
| Variable | Process | Notes |
|---|---|---|
LOG_LEVEL | worker | trace/debug/info/warn/error. Defaults to info |
PORT | web | Assigned by most hosts. The server binds it and the internal tRPC client follows it |
Example
A complete .env.example lives at the repo root. Copy it to
apps/web/.env.local to start.