Environment variables

Exhaustive list of environment variables recognized by arka-deck. Source of truth: .env.example at the root, addons/cortex-lite/.env.example for the embedded sidecar, and effective reads at boot.

Web server

Variable	Default	Description
`ARKA_DECK_WEB_PORT`	`3117`	HTTP server port
`ARKA_DECK_WEB_HOST`	`127.0.0.1` (or `0.0.0.0` if `--lan`)	Bind address
`ARKA_DECK_WEB_LAN`	`0`	Enables LAN mode if `1`, `true` or `yes` (priority 2, see CLI)
`ARKA_DECK_WEB_BASE_URL`	derived from host/port	Override the public base URL emitted by the server (OAuth callbacks, links)
`ARKA_DECK_LOG`	`info`	Fastify log level (`fatal`/`error`/`warn`/`info`/`debug`/`trace`/`silent`)
`ARKA_DECK_RATE_LIMIT_MAX`	`300`	Rate limit ceiling / minute
`ARKA_DECK_RATE_LIMIT_WINDOW`	`1 minute`	Rate limit window (Fastify rate-limit syntax)

Storage and home

Variable	Default	Description
`ARKA_DECK_HOME`	`~/.arka-deck/`	Override the global user folder
`ARKA_PLATFORM_DIR`	platform-specific	Override the platform data directory (advanced)

Cortex (catalogue + MCP)

Variable	Default	Description
`ARKA_DECK_CORTEX_URL`	`https://public.arkalabs.app`	Cortex endpoint for the catalogue (read-only)
`ARKA_DECK_CORTEX_MCP_URL`	`https://mcp.public.arkalabs.app`	Cortex MCP endpoint for agents
`ARKA_DECK_CORTEX_RUNTIME_URL`	(unset, loopback fallback)	Dedicated Cortex runtime endpoint

Anti-SSRF policy

By default, the ARKA_DECK_CORTEX_URL, ARKA_DECK_CORTEX_MCP_URL and ARKA_DECK_CORTEX_RUNTIME_URL overrides accept only:

Loopback (127.0.0.1, localhost) — for local Cortex Lite
HTTPS hosts on *.arkalabs.app

Any other host is refused. To bypass in development:

ARKA_DECK_CORTEX_ALLOW_UNSAFE_URL=1

This variable must never be set in production.

See ADR 0006.

Cortex Lite sidecar

These variables are read by the embedded addons/cortex-lite sidecar (SurrealDB + Express REST + optional MCP stdio). When arka-deck launches the sidecar through Docker compose, it forwards the variables present in the host environment.

Schema source: addons/cortex-lite/.env.example.

Process

Variable	Default	Description
`MODE`	`api`	Process mode: `api` (HTTP REST) or `mcp` (stdio MCP)
`PORT`	`9100`	HTTP listen port (loopback-only via docker-compose bind `127.0.0.1:${PORT}:9100`)
`CORTEX_LITE_MCP_DISABLED`	unset	When set (`1`/`true`), the MCP stdio server is not started even in `MODE=mcp`
`CORTEX_LITE_COMPOSE_FILE`	bundled `docker-compose.yml`	Override the compose file used by the launcher

SurrealDB

Variable	Default	Description
`SURREAL_URL`	`http://127.0.0.1:8000`	SurrealDB endpoint
`SURREAL_USER`	`root`	DB user
`SURREAL_PASS`	(unset, no default)	DB password — never reuse `root` outside ephemeral dev
`SURREAL_NS`	`cortex`	SurrealDB namespace
`SURREAL_DB`	`lite`	SurrealDB database
`DB_INIT_RETRY_MS`	`1000`	Delay between DB bootstrap attempts (ms)
`DB_INIT_MAX_ATTEMPTS`	`30`	Max DB bootstrap attempts before giving up

Auth and CORS

Variable	Default	Description
`API_KEYS`	(unset)	JSON array `[{ "key": "...", "role": "admin"\|"readonly", "label": "..." }]` — generate keys via `openssl rand -hex 32`
`CORTEX_LITE_DEV_AUTH`	unset	When `1`, the magic value `dev-key-lite` is accepted as an admin key. Sandbox only
`CORS_ORIGIN`	loopback-only	Comma-separated allowlist. `*` is accepted only when set explicitly
`ARKA_TOKEN`	(unset)	Shared LAN token between arka-deck and Cortex Lite (auto-injected as admin)

The API key check uses crypto.timingSafeEqual over SHA-256 hashes (constant-time across the cached key set and the ARKA_TOKEN branch).

Endpoint URL (`CORTEX_PUBLIC_URL`)

Variable	Default	Description
`CORTEX_PUBLIC_URL`	`https://public.arkalabs.app`	Read-only upstream Cortex catalogue URL

The sidecar applies the same anti-SSRF policy as the arka-deck core (HTTPS + arkalabs.app only). The dev override is the shared ARKA_DECK_CORTEX_ALLOW_UNSAFE_URL=1 — keep it consistent across both surfaces.

Rate limit — explicit deferral

The Cortex Lite Express app does not carry its own rate-limit middleware. Justification:

the sidecar is published on loopback only (127.0.0.1:9100 Docker bind);
any LAN flood path goes through the arka-deck Fastify reverse proxy, which already enforces ARKA_DECK_RATE_LIMIT_MAX / ARKA_DECK_RATE_LIMIT_WINDOW;
the payload is capped at 2 MB (express.json({ limit: '2mb' })).

If Cortex Lite is ever exposed beyond loopback, add express-rate-limit (target 600 req/min, allowlist 127.0.0.1) and update this section.

Ingestion / sync scheduler

Variable	Default	Description
`INGEST_BATCH_SIZE`	`20`	Atoms per batch when syncing the public catalogue
`INGEST_DELAY_MS`	`100`	Delay between batches (ms), to be gentle on the public Cortex
`INGEST_FETCH_CONTENT`	unset	Fetch full atom content during ingestion (`1`/`true`) or only summary
`SYNC_INTERVAL_HOURS`	`24`	Frequency of the automatic resync
`SYNC_ON_START`	`true`	Trigger an immediate sync at startup

External connectors

Variable	Description
`ARKA_DECK_NOTION_OAUTH_CLIENT_ID`	Notion OAuth client ID (first-party integration)
`ARKA_DECK_NOTION_OAUTH_CLIENT_SECRET`	Notion OAuth client secret
`ARKA_DECK_NOTION_OAUTH_REDIRECT_URI`	Notion OAuth callback URL, usually `/api/connectors/installations/oauth/callback`
`NOTION_OAUTH_CLIENT_ID`	Legacy alias (deprecated; prefer the `ARKA_DECK_*` form)
`NOTION_OAUTH_CLIENT_SECRET`	Legacy alias (deprecated; prefer the `ARKA_DECK_*` form)
`NOTION_OAUTH_REDIRECT_URI`	Legacy alias (deprecated; prefer the `ARKA_DECK_*` form)

OAuth variables are only needed if you use the Notion browser OAuth flow. Notion can still use an internal integration token.

Gmail and Google Drive do not use global arka-deck OAuth variables. Their API token/gateway token and optional MCP endpoint are configured per connector installation from the UI.

Other runtime flags

Variable	Default	Description
`ARKA_DECK_MCP_PROBE`	`1`	When `0`, the MCP endpoint probe is skipped during installs
`ARKA_DECK_ENABLE_CUSTOM_STDIO_MCP`	`0`	Enables custom STDIO MCP server registration
`ARKA_DECK_GOOGLE_GENAI_ALLOW_UNSAFE_BASE_URL`	unset	DEV ONLY — disables Google GenAI base URL anti-SSRF check
`ARKA_REFUSE_DRAFT`	unset	Defensive flag for tests: refuse to send drafts through external connectors

E2E tests

Variable	Description
`PLAYWRIGHT_BASE_URL`	Base URL for Playwright tests (default `http://127.0.0.1:3117`)
`ARKA_E2E_PORT`	Alternate listen port used by the Playwright web server
`ARKA_SMOKE_SKIP_BUILD`	Smoke test helper: skip the build phase in `scripts/smoke-binary.sh`

Best practices

Put overrides in .env.local (never in a versioned .env).
Never commit an API key. The historical dev-key-lite Cortex Lite value is refused unless CORTEX_LITE_DEV_AUTH=1 is set explicitly.
For persistent secrets, use the Settings → Providers UI rather than an environment variable (AES-256-GCM encryption).
Check .env.example at the root and addons/cortex-lite/.env.example for the maintained list.