Environment variables

Every variable the server reads, with its validation, default, and effect.

Configuration is one Zod schema parsed at module import time. A validation failure crashes the process on boot, before routes are registered or plugins load — so a bad value fails loudly and immediately rather than at first use.

Two variables are genuinely required. Everything else has a default.

Both default to "" outside tests, and "" fails validation — which is how the requirement is enforced. When NODE_ENV=test they fall back to fixed development values so the suite runs without setup.

Core#

Database#

DATABASE_URL does more than pick a database: the browser-profile directory and the jots directory both default to siblings of its dirname.

Authentication and SSO#

Keycloak counts as configured only when all three of its variables are set. The Google callback URL is ${SERVER_PUBLIC_URL}/api/auth/google/callback and the Keycloak one is ${SERVER_PUBLIC_URL}/api/auth/keycloak/callback — both server-side, not portal-side.

OAuth server (MCP clients)#

Browser sessions#

Capture proxy — read straight from process.env#

These three are not in the config schema, so they are invisible to the boot-time validation and easy to miss when reading config.ts. They are read directly where Chromium is spawned.

Proxy authentication is armed only when all three are set. The answering handler responds to proxy auth challenges specifically, and declines anything else. Because they bypass the schema, a typo in one of these names fails silently rather than at boot.

Jots#

Cluster#

Note the enum: an arbitrary truthy-looking string such as yes is a validation error that crashes the boot, not a falsy value.

Audit and telemetry#

sqlite writes to whatever backend DATABASE_URL selects, PostgreSQL included, despite the name.

There is no variable for tracing. OpenTelemetry instrumentation is registered but starts with no exporter configured, so spans are produced and nothing exports them by default. Any export has to come from the standard OTEL_* variables the OTel SDK reads on its own.

Plugin credentials#

Per-plugin OAuth clients are read directly from process.env by name, not declared in the schema. The prefix is the plugin name converted from kebab-case to UPPER_SNAKE_CASE.

There are 16 built-in plugins. The 14 that use OAuth, by the prefix they take: ASANA, ATLASSIAN_BITBUCKET, ATLASSIAN_CONFLUENCE, ATLASSIAN_JIRA, GITHUB, GITLAB, GOOGLE_CALENDAR, GOOGLE_DOCS, GOOGLE_DRIVE, GOOGLE_GEMINI, GOOGLE_GMAIL, GOOGLE_SHEETS, GOOGLE_SLIDES, SLACK.

The other two take no _CLIENT_ID because they do not use OAuth: newrelic (NEWRELIC) is API-key auth, and httpbin-cookie (HTTPBIN_COOKIE) is cookie auth.

<PLUGIN>_ALLOWED_INSTANCES entries are each normalised: https only, no userinfo in the URL, and no private or loopback address literals. The manifest's cloud default is always allowed — with the variable unset, it is the only allowed origin. This is what stops a shared client secret being POSTed to an attacker-chosen host.

New Relic's key, region, and account ID are entered per user in the portal — the running server never reads them from the environment. The one exception is the shipped verification script, below.

Migration and tooling#

Read only by the shipped scripts and by tests — never by the running server.