Environment variables

The complete list of env vars the host reads. All come from .env.<env> (loaded via scripts/load-env.sh) — the host doesn’t read environment variables outside that flow.

Required

Var	Purpose	Notes
DATABASE_URL	Postgres connection string	Name MUST end with _dev / _staging / _prod so the reset guardrail classifies it
HOST_MASTER_KEY	32-byte hex AES-256-GCM key	Generate with ./scripts/gen-secret.sh 32. Different per env. Host refuses to boot without it.
OPENCLAW_GATEWAY_PASSWORD	Bearer token for the OpenClaw gateway	Must match ~/.openclaw/config.toml. See OpenClaw setup

Optional — networking

Var	Default	Purpose
HOST	::	Bind address. Dual-stack default works for both IPv4 + IPv6 + Tailscale
PORT	3000	HTTP port

Optional — OpenClaw

Var	Default	Purpose
OPENCLAW_GATEWAY_URL	http://localhost:18789	Gateway address. Override only for non-default ports
OPENCLAW_WORKSPACE_DIR	~/.openclaw/workspace	Where the dream-cycle reads DREAMS.md from
OPENCLAW_CONFIG_PATH	<repo>/openclaw.config.json	Carabase’s own MCP-server config for OpenClaw to consume

Optional — workspace

Var	Default	Purpose
DEFAULT_WORKSPACE_ID	(unset)	When set, enables the cron schedulers (GitHub sync, calendar sync, memory distillation, etc.). Background workers stay dormant without it.
HOST_FILE_WATCHER	0	Set to 1 for headless deployments without the desktop client. Enables the chokidar file watcher for local markdown / calendar files

Optional — LLM bootstrap (background work only)

The chat path goes through OpenClaw’s own model config — see OpenClaw setup. These env vars are read by background workers (harvest, embeddings, summary) as a fallback for when model routing isn’t yet configured in the Admin SPA.

Var	Purpose
OPENAI_API_KEY	OpenAI key for utility-* tiers + embeddings
OPENROUTER_API_KEY	OpenRouter key (alternative to OpenAI)
OLLAMA_URL	Local Ollama server (alternative to a hosted provider)
EMBEDDING_MODEL	Override the default embedding model
LLM_MODEL	Override the default chat model
EMBEDDING_DIMENSIONS	Vector dim. Default 4096. Change requires a migration regen

These are scheduled to move to a deprecation warning once the first-run wizard handles model routing more aggressively.

Optional — harvester / connectors

Var	Purpose
HARVEST_LLM_PROVIDER	ollama / openai / openrouter for the harvest pipeline
HARVEST_LLM_MODEL	Model for entity extraction
HARVEST_CONCURRENCY	Max parallel harvest jobs (default 3)
WHISPER_PROVIDER	Voice transcription provider (auto-detected if blank)
WHISPER_MODEL	Transcription model name
DISTILL_LLM_PROVIDER / DISTILL_LLM_MODEL	Memory-distillation overrides
BRIDGE_LLM_PROVIDER / BRIDGE_LLM_MODEL	Memory-graph bridge overrides
GITHUB_REPOS	Comma-separated owner/repo list for GitHub sync (sync-rules supersede this)
GOOGLE_CALENDAR_ID	Calendar to sync (default primary)
HARVESTER_DEVICE_AUTH_REQUIRED	Strict mode for edge harvester push auth (default off)

Removed in v0.1

These USED to be honored as fallbacks but were ripped out for the OSS launch:

• GITHUB_OAUTH_CLIENT_ID — store in encrypted oauth_apps table via Admin SPA → OAuth Apps
• GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET — same
• GITHUB_TOKEN — populated by GitHub device-flow OAuth into the integrations table
• GOOGLE_CALENDAR_TOKEN — populated by Google OAuth into integrations

If you have any of these set in a leftover .env.<env>, the host returns 503 Not Configured on the affected auth route with a message pointing you at the correct config surface.