Environment Variables

Canonical source: docs/06-data/environment-variables.md — this page is rendered from it on every publish; edit the source.

Environment Variables

Complete reference for all environment variables used by Claw.

All variables are defined in .env.example at the project root. Copy it to .env and fill in secrets before starting.

---

General

Variable	Required	Default	Description
NODE_ENV	No	development	development or production
CORS_ORIGINS	Yes	http://localhost:3000	Comma-separated allowed origins for CORS
THROTTLE_TTL	No	60000	Rate-limit window in milliseconds
THROTTLE_LIMIT	No	2500	Max requests per window per user/IP

---

Shared outbound email

The frontend contact route and payment-service invoice worker use the same server-only SMTP configuration and the shared hardened transport adapter. Invoice PDFs remain available through authenticated download when delivery is disabled.

Variable	Required	Default	Description
CONTACT_EMAIL_ENABLED	No	false	Enables configured outbound delivery
CONTACT_EMAIL_PROVIDER	No	none	smtp for real delivery; none disables it
CONTACT_EMAIL_FROM	When SMTP is enabled	no-reply@claw-ai.co	Verified sender used by contact and invoice mail
CONTACT_SMTP_HOST	When SMTP is enabled	—	SMTP relay host
CONTACT_SMTP_PORT	No	587	465 implicit TLS; other ports require STARTTLS
CONTACT_SMTP_SECURE	No	false	Operator hint; TLS mode is safely derived by port
CONTACT_SMTP_USER	When SMTP is enabled	—	SMTP username
CONTACT_SMTP_PASS	When SMTP is enabled	—	SMTP password; never log or expose
VAPID_PUBLIC_KEY	Web Push	—	VAPID public key for portal push notifications (auth-service). All three VAPID vars or none; a partial set leaves push off
VAPID_PRIVATE_KEY	Web Push	—	VAPID private key; a secret, never log or expose
VAPID_SUBJECT	Web Push	—	mailto: or https: contact the push service may use

CONTACT_EMAIL_TO, CONTACT_RATE_LIMIT_MAX, and CONTACT_RATE_LIMIT_WINDOW_MS are contact-form-only. Invoice delivery uses the recipient frozen from the authenticated checkout and never accepts a webhook recipient.

---

Production Deployment Control

Read by auth-service only, for the admin deployment page. See PRODUCTION_DEPLOYMENT.md §2.8.

Variable	Required	Default	Description
DEPLOYMENT_STATUS_FILE	No	/app/.deploy/status.json	Rollout record deploy-prod.sh writes
DEPLOYMENT_AUTOMATION_FILE	No	/app/.deploy/automation.json	Automatic-deploy switch the page writes
GITHUB_DEPLOY_TOKEN	Fallback only	—	Fine-grained PAT, Actions read+write only; never log or expose
GITHUB_DEPLOY_REPOSITORY	Fallback only	—	owner/repo the deployment workflow lives in
GITHUB_DEPLOY_REF	Fallback only	—	Git ref a manual dispatch targets, normally main

The three GITHUB_DEPLOY_* values are a fallback. Credentials are normally configured from /admin/deployment and stored encrypted in auth-service's database; a stored set always wins over the environment. Set them here only to provision a fresh box from .env, or to keep an existing one deploying before anyone opens the page.

They are required together. A partial set leaves manual deployment disabled and the page hides the controls; it does not half-enable them. A blank value in .env means unset, not empty-string.

---

PostgreSQL Instances

Claw uses 15 separate PostgreSQL instances, one per data-owning service.

Variable	Required	Default	Description
PG_AUTH_HOST	Yes	claw-pg-auth	Auth database host
PG_AUTH_PORT	Yes	5432	Auth database port (internal)
PG_AUTH_USER	Yes	claw	Auth database username
PG_AUTH_PASSWORD	Yes	claw_secret	Auth database password
PG_AUTH_DB	Yes	claw_auth	Auth database name
PG_CHAT_HOST	Yes	claw-pg-chat	Chat database host
PG_CHAT_PORT	Yes	5432	Chat database port
PG_CHAT_USER	Yes	claw	Chat database username
PG_CHAT_PASSWORD	Yes	claw_secret	Chat database password
PG_CHAT_DB	Yes	claw_chat	Chat database name
PG_CONNECTORS_HOST	Yes	claw-pg-connector	Connector database host
PG_CONNECTORS_PORT	Yes	5432	Connector database port
PG_CONNECTORS_USER	Yes	claw	Connector database username
PG_CONNECTORS_PASSWORD	Yes	claw_secret	Connector database password
PG_CONNECTORS_DB	Yes	claw_connectors	Connector database name
PG_ROUTING_HOST	Yes	claw-pg-routing	Routing database host
PG_ROUTING_PORT	Yes	5432	Routing database port
PG_ROUTING_USER	Yes	claw	Routing database username
PG_ROUTING_PASSWORD	Yes	claw_secret	Routing database password
PG_ROUTING_DB	Yes	claw_routing	Routing database name
PG_MEMORY_HOST	Yes	claw-pg-memory	Memory database host
PG_MEMORY_PORT	Yes	5432	Memory database port
PG_MEMORY_USER	Yes	claw	Memory database username
PG_MEMORY_PASSWORD	Yes	claw_secret	Memory database password
PG_MEMORY_DB	Yes	claw_memory	Memory database name
PG_FILES_HOST	Yes	claw-pg-files	File database host
PG_FILES_PORT	Yes	5432	File database port
PG_FILES_USER	Yes	claw	File database username
PG_FILES_PASSWORD	Yes	claw_secret	File database password
PG_FILES_DB	Yes	claw_files	File database name
PG_OLLAMA_HOST	Yes	claw-pg-ollama	Ollama service database host
PG_OLLAMA_PORT	Yes	5432	Ollama service database port
PG_OLLAMA_USER	Yes	claw	Ollama service database username
PG_OLLAMA_PASSWORD	Yes	claw_secret	Ollama service database password
PG_OLLAMA_DB	Yes	claw_ollama	Ollama service database name
PG_IMAGES_HOST	Yes	claw-pg-images	Image service database host
PG_IMAGES_PORT	Yes	5432	Image service database port
PG_IMAGES_USER	Yes	claw	Image service database username
PG_IMAGES_PASSWORD	Yes	claw_secret	Image service database password
PG_IMAGES_DB	Yes	claw_images	Image service database name
PG_FILE_GENERATIONS_HOST	Yes	claw-pg-file-generations	File gen database host
PG_FILE_GENERATIONS_PORT	Yes	5432	File gen database port
PG_FILE_GENERATIONS_USER	Yes	claw	File gen database username
PG_FILE_GENERATIONS_PASSWORD	Yes	claw_secret	File gen database password
PG_FILE_GENERATIONS_DB	Yes	claw_file_generations	File gen database name
PG_AGENT_HOST	Yes	claw-pg-agent	Agent service database host
PG_AGENT_PORT	Yes	5432	Agent service database port
PG_AGENT_USER	Yes	claw	Agent service database username
PG_AGENT_PASSWORD	Yes	claw_secret	Agent service database password
PG_AGENT_DB	Yes	claw_agent	Agent service database name
PG_RESEARCH_HOST	Yes	claw-pg-research	Research service database host
PG_RESEARCH_PORT	Yes	5432	Research service database port
PG_RESEARCH_USER	Yes	claw	Research service database username
PG_RESEARCH_PASSWORD	Yes	claw_secret	Research service database password
PG_RESEARCH_DB	Yes	claw_research	Research service database name
PG_WORKSPACE_HOST	Yes	claw-pg-workspace	Workspace service database host
PG_WORKSPACE_PORT	Yes	5432	Workspace service database port
PG_WORKSPACE_USER	Yes	claw	Workspace service database username
PG_WORKSPACE_PASSWORD	Yes	claw_secret	Workspace service database password
PG_WORKSPACE_DB	Yes	claw_workspace	Workspace service database name
PG_PAYMENTS_PORT	Yes	5453	Payment database host port
PG_PAYMENTS_USER	Yes	claw	Payment database username
PG_PAYMENTS_PASSWORD	Yes	claw_secret	Payment database password
PG_PAYMENTS_DB	Yes	claw_payments	Payment database name
PG_THREAD_GENERATION_PORT	Yes	5457	Threads generation database host port
PG_THREAD_GENERATION_USER	Yes	claw	Threads generation database username
PG_THREAD_GENERATION_PASSWORD	Yes	generated by installer	Threads generation database password
PG_THREAD_GENERATION_DB	Yes	claw_thread_generation	Threads generation database name
PG_THREADS_PORT	Yes	5458	Threads publication database host port
PG_THREADS_USER	Yes	claw	Threads publication database username
PG_THREADS_PASSWORD	Yes	generated by installer	Threads publication database password
PG_THREADS_DB	Yes	claw_threads	Threads publication database name
PG_PLUGIN_PORT	Yes	5459	Plugin service database host port
PG_PLUGIN_USER	Yes	claw	Plugin service database username
PG_PLUGIN_PASSWORD	Yes	generated by installer	Plugin service database password
PG_PLUGIN_DB	Yes	claw_plugin	Plugin service database name

Notes:

• Inside Docker Compose, services use Docker service names as hosts (e.g., claw-pg-auth) with internal port 5432.
• When running services locally (outside Docker), use localhost with the host port (e.g., 5441 for auth).
• Each PostgreSQL instance is a separate Docker container for fault isolation.
• The generation service uses THREAD_GENERATION_DATABASE_URL; the installer derives its password from PG_THREAD_GENERATION_PASSWORD.
• The publication service uses THREADS_DATABASE_URL; the installer derives its password from PG_THREADS_PASSWORD. It also reads CONNECTOR_SERVICE_URL (default http://connector-service:4003) to check at enqueue and retry that each chosen model is in the model picker catalog by exact match (ADR-174 and its 2026-10-14 addendum); the shared value from .env is used, no new variable. It reads ROUTING_SERVICE_URL again (ADR-198, 2026-10-31) for POST /internal/router-models/costs/classes, so a cost-class plan can tell a cheap model from a premium one; the shared .env value is used. workspace-service reads the same variable for AUTO model choice.
• The plugin service uses PLUGIN_DATABASE_URL; the installer derives its password from PG_PLUGIN_PASSWORD.
• Memory service uses pgvector extension for embedding similarity search.

---

MongoDB

Variable	Required	Default	Description
MONGO_HOST	Yes	claw-mongodb	MongoDB host
MONGO_PORT	Yes	27017	MongoDB port (internal)
MONGO_USER	No	—	MongoDB username (if auth enabled)
MONGO_PASSWORD	No	—	MongoDB password (if auth enabled)

Notes:

• Used by Audit service (claw_audit), Client Logs service (claw_client_logs), and Server Logs service (claw_server_logs).
• Internal Docker port is 27017; host port is 27018.
• All log collections have a 30-day TTL index.

---

Redis

Variable	Required	Default	Description
REDIS_HOST	Yes	claw-redis	Redis host
REDIS_PORT	Yes	6379	Redis port (internal)
REDIS_URL	No	redis://claw-redis:6379	Redis connection URL

Notes:

• Used by Ollama service for state, by routing service for prompt cache (5-minute TTL), and by throttler middleware for rate-limit counters.
• Internal port 6379; host port 6380.

---

RabbitMQ

Variable	Required	Default	Description
RABBITMQ_HOST	Yes	claw-rabbitmq	RabbitMQ host
RABBITMQ_PORT	Yes	5672	RabbitMQ AMQP port
RABBITMQ_USER	Yes	guest	RabbitMQ username
RABBITMQ_PASSWORD	Yes	guest	RabbitMQ password
RABBITMQ_URL	No	(built from above)	Full AMQP URL
RABBITMQ_MGMT_PORT	No	15672	RabbitMQ management UI port

Notes:

• Topic exchange claw.events with dead-letter queue and 3 retries with backoff.
• Change default credentials in production.

---

Authentication / JWT

Variable	Required	Default	Description
JWT_SECRET	Yes	—	Secret key for signing JWTs (minimum 32 characters)
JWT_ACCESS_EXPIRY	No	15m	Access token lifetime (e.g., 15m, 1h)
JWT_REFRESH_EXPIRY	No	7d	Refresh token lifetime (e.g., 7d, 30d)

Notes:

• Generate with: openssl rand -base64 48
• Every microservice validates JWTs independently using @claw/shared-auth.

---

Grafana (ADR-115)

Variable	Required	Default	Description
GRAFANA_SECRET_KEY	No	Grafana's own default	Grafana's internal secret-storage encryption key. Blank keeps Grafana's default, acceptable because nothing stored in Grafana is encrypted yet.

Notes:

• There is no Grafana admin password variable — Grafana has no built-in admin and no login of its own. Access is the admin's own session, proxied through a short-lived cookie auth-service mints; see ADR-115.
• Generate with: openssl rand -hex 32

---

Encryption

Variable	Required	Default	Description
ENCRYPTION_KEY	Yes	—	32-byte hex string (64 hex characters) for AES-256-GCM

Notes:

• Used by Connector service to encrypt provider API keys at rest.
• Generate with: openssl rand -hex 32
• Never commit this value to version control.

Variable	Required	Default	Description
PLUGIN_ENCRYPTION_KEY	Yes	—	32-byte hex string (64 hex characters) for AES-256-GCM over MCP credentials, plugin-service

• PLUGIN_ENCRYPTION_KEY is deliberately separate from ENCRYPTION_KEY so a leak in one service does not expose the other. The installer generates it and preserves it on re-install (changing it orphans stored credentials). plugin-service refuses to start when it is missing, shorter or longer than 64 characters, not hex, or all zeros (ADR-172); it also reads RABBITMQ_URL for the user.deleted consumer.

---

Admin Seed

Variable	Required	Default	Description
ADMIN_EMAIL	No	admin@claw.local	Email for the seeded admin account
ADMIN_USERNAME	No	claw-admin	Username for the seeded admin account
ADMIN_PASSWORD	Yes	change-me-on-first-login	Password for the seeded admin account

---

Frontend

Variable	Required	Default	Description
NEXT_PUBLIC_API_URL	Yes	http://localhost:4000	API URL via Nginx (accessible from browser)
NEXT_PUBLIC_APP_NAME	No	Claw	Application display name
NEXT_PUBLIC_APP_URL	No	http://localhost:3000	Frontend public URL
FRONTEND_PORT	No	3000	Port the Next.js frontend listens on
SITE_URL	Production	—	Canonical HTTPS bare origin; enables crawling
CHAT_SERVICE_URL	Production	—	Server-only chat-service origin for public shares/discovery
INTER_SERVICE_AUTH_TOKEN	Production	—	Server-only credential for protected internal feeds
TRUSTED_PROXY_ADDRESSES	Distributed nginx only	blank	Comma list of IPs/CIDRs whose X-Real-IP services believe, besides loopback and the docker nginx (rules/58 item 3)

Notes:

• Variables prefixed with NEXT_PUBLIC_ are embedded in the browser bundle. Never put secrets here.
• SITE_URL is deliberately fail-closed: preview, local, missing, or invalid values produce global noindex and robots.txt disallow-all.
• Never expose CHAT_SERVICE_URL or INTER_SERVICE_AUTH_TOKEN with a NEXT_PUBLIC_ prefix.

---

Ollama (Local AI Runtime)

Variable	Required	Default	Description
OLLAMA_BASE_URL	Yes	http://claw-ollama:11434	Ollama HTTP API base URL
LOCAL_SPEECH_BASE_URL	No	http://speech:8000	Free local speech container (ADR-128), used by file-service (STT) and chat-service (read aloud). Blank = off
OLLAMA_ROUTER_MODEL	No	deepseek-v4-pro	Model that PLANS the route (never answers the user). Cloud, not local — routing quality caps answer quality.
OLLAMA_ROUTER_TIMEOUT_MS	No	10000	Timeout for router model calls (ms)
ROUTER_COMPACT_PROMPT	No	true	Toggles compact vs expanded AUTO router prompt layout
OLLAMA_GENERATE_TIMEOUT_MS	No	300000	Timeout for non-router generation calls (ms)
OLLAMA_CHAT_TIMEOUT_MS	No	300000	Timeout for native /api/chat calls — the tool-calling surface (ms)
OLLAMA_API_KEY	No	—	Bearer key for a signed-in local Ollama proxying to Cloud models
OLLAMA_KEEP_ALIVE	No	-1m	How long the runtime keeps a model resident; -1m = forever until evicted
OLLAMA_MAX_LOADED_MODELS	No	2	Max number of models loaded into VRAM concurrently
OLLAMA_NUM_PARALLEL	No	1	Parallel generation slots per loaded model
OLLAMA_FLASH_ATTENTION	No	1	Enable flash-attention kernel when supported by the GPU
OLLAMA_KV_CACHE_TYPE	No	q8_0	KV-cache quantization (f16, q8_0, q4_0)
MEMORY_EXTRACTION_MODEL	No	AUTO	Model used for memory extraction (AUTO picks best installed)
AUTO_PULL_MODELS	No	qwen3:1.7b	Space-separated list of models to auto-pull on startup

Runtime V2 provider-native tool calling (chat-service)

Variable	Required	Default	Description
CHAT_NATIVE_TOOL_CALLING_ENABLED	No	true	Translate the admitted Runtime V2 tool catalog into the provider's native tool dialect and parse tool calls back
CHAT_TOOL_CATALOG_MAX_BYTES	No	262144	Byte budget for the serialized catalog, which is re-sent on every turn of a tool loop

Variable	Required	Default	Description
LLAMACPP_ENABLE_JINJA	No	true	Launch tool-capable catalog entries with --jinja so llama-server parses emitted tool calls

--jinja is applied per catalog entry — only entries whose capabilities include tools — never globally. A GGUF whose embedded chat template is not tool-aware can fail to start under --jinja, so gating per entry means a bad template can never take down a model that never needed tools. LLAMACPP_ENABLE_JINJA=false is the kill switch if an upstream llama.cpp release regresses.

When CHAT_NATIVE_TOOL_CALLING_ENABLED is false, every provider resolves to the NONE tool dialect and Runtime V2 falls back to the prompt-JSON compatibility lane. That lane serializes the catalog into the system prompt as text and cannot express a real tool call, so a model on it will truthfully report that it has no filesystem, terminal or browser. Keep it on unless a deployment has a specific reason to degrade.

Headless-browser rendering fallback (research-service)

Variable	Required	Default	Description
RESEARCH_HEADLESS_RENDER_ENABLED	No	true	Hard kill switch for the Patchright headless tier of the fetch escalation chain (ADR-121)
CLAW_SCRAPER_PROFILES	No	(empty)	Which scraping sidecars exist: subset of crawl4ai,flaresolverr,firecrawl (compose profiles)
FIRECRAWL_POSTGRES_PASSWORD	No	internal default	Firecrawl sidecar's private Postgres; generated by the installers
FIRECRAWL_BULL_AUTH_KEY	No	(empty)	Firecrawl sidecar's queue-admin key; generated by the installers
CRAWL4AI_API_TOKEN	For Crawl4AI	(empty)	Secret. Bearer token shared by the crawl4ai container and research-service. Crawl4AI 0.9.x binds 0.0.0.0 and requires it only when set; blank = loopback-only sidecar and the CRAWL4AI tier is skipped as unavailable. Generated (and preserved) by the installers; by hand openssl rand -hex 32

Which tiers of the escalation chain run is DB-level (FetchStrategyConfig, admin PATCH /api/v1/research/fetch-strategies/:kind), not env. The env switch above can only take the in-process browser OUT (a resource lever, not a safety one: every in-page request is SSRF-checked either way). CLAW_SCRAPER_PROFILES is env only because which containers exist must be decided before anything runs; a started sidecar is still off until enabled in the DB. See ADR-121 and skills/add-a-fetch-strategy.md.

Notes:

• Inside Docker, use the container service name as host (claw-ollama).
• When running Ollama on the host, use http://host.docker.internal:11434.
• Router models are auto-excluded from user-facing model selector dropdowns.

---

File Storage

Variable	Required	Default	Description
FILE_STORAGE_PATH	Yes	/data/uploads	Absolute path where uploaded files are stored
CLAMAV_HOST	No	clamav	ClamAV container host
CLAMAV_PORT	No	3310	ClamAV TCP port
CLAMAV_ENABLED	No	true	Enable/disable antivirus scanning

---

Image Service

Variable	Required	Default	Description
IMAGE_SERVICE_URL	Yes	http://claw-image-service:4012	Internal image service URL
IMAGE_PORT	No	4012	Image service port
STABLE_DIFFUSION_URL	No	http://claw-comfyui:8188	ComfyUI / Stable Diffusion URL
COMFYUI_BASE_URL	No	http://claw-comfyui:8188	ComfyUI API base URL
COMFYUI_PORT	No	8188	ComfyUI container port

---

Payment and Billing

Prices are database-owned immutable PlanPriceVersion records, not environment variables. The payment service validates the variables below at startup. Leave a gateway's full credential set blank to disable it; partial configuration is rejected.

Variable	Required	Default	Purpose
PAYMENT_DATABASE_URL	Yes	—	Payment-service PostgreSQL connection
PAYMENT_SERVICE_PORT	No	4018	Payment-service listen port
AUTH_SERVICE_URL, ROUTING_SERVICE_URL	Yes	service-local URLs	Signed internal plan, entitlement, and provider-cost contracts
INTER_SERVICE_AUTH_TOKEN	Yes	—	Minimum 32-character internal request signing secret
FRONTEND_URL	Yes	https://claw.local	Server-owned checkout return origin
PAYMENT_TOKEN_ENCRYPTION_KEY	Yes	—	64-character hex key for vaulted gateway tokens
PAYMENT_TOKEN_KEY_VERSION	No	1	Ciphertext key version used during rotation
PAYPAL_CLIENT_ID, PAYPAL_CLIENT_SECRET, PAYPAL_WEBHOOK_ID	To enable PayPal	—	Complete PayPal server credential set
PAYPAL_ENV	No	sandbox	sandbox or live; configured production requires live
NEXT_PUBLIC_PAYPAL_CLIENT_ID	To render PayPal	—	Public browser client identifier
PAYMOB_SECRET_KEY, PAYMOB_PUBLIC_KEY, PAYMOB_HMAC_SECRET	To enable Paymob	—	Complete Paymob secret/public/HMAC set
PAYMOB_API_KEY	To enable Paymob	—	Required: exchanged for the auth token every Paymob call uses
PAYMOB_CARD_INTEGRATION_ID	To enable Paymob	—	Paymob hosted-card integration
PAYMOB_CURRENCY, NEXT_PUBLIC_PAYMOB_PUBLIC_KEY	No / render Paymob	EGP / —	Settlement currency and safe browser key
EXCHANGE_RATE_API_BASE_URL, EXCHANGE_RATE_CACHE_TTL_MS	No	provider / 3600000	FX source and cache lifetime
USD_TO_EGP_FALLBACK_RATE	No	0	Non-zero emergency fallback; zero fails closed
FX_QUOTE_TTL_MS, FX_SAFETY_MARGIN_BPS	No	900000 / 150	Bound quote lifetime and adverse-movement margin
WEBHOOK_REPLAY_TOLERANCE_MS, BILLING_GRACE_PERIOD_MS	No	600000 / 259200000	Replay window and past-due entitlement grace
BILLING_RECONCILIATION_CRON	No	0 */15 * * * *	Reconciliation schedule
PAYMENT_OUTBOX_POLL_INTERVAL_MS, PAYMENT_OUTBOX_MAX_ATTEMPTS	No	5000 / 10	Outbox drain cadence and dead-letter threshold
PAYMENT_GATEWAY_TIMEOUT_MS, PAYMENT_GATEWAY_MAX_RETRIES	No	20000 / 2	Bounded provider calls and safe/idempotent retries

Invoice delivery uses the shared SMTP variables above. In distributed nginx, set CLAW_PAYMENT_ORIGIN to the payment deployment origin; expose only /payments/webhooks, /payments, /billing, and /admin/billing, never /internal/*.

---

Inter-Service URLs

All services communicate via internal Docker service names.

Variable	Required	Default
AUTH_SERVICE_URL	Yes	http://claw-auth-service:4001
CHAT_SERVICE_URL	Yes	http://claw-chat-service:4002
CONNECTOR_SERVICE_URL	Yes	http://claw-connector-service:4003
ROUTING_SERVICE_URL	Yes	http://claw-routing-service:4004
MEMORY_SERVICE_URL	Yes	http://claw-memory-service:4005
FILE_SERVICE_URL	Yes	http://claw-file-service:4006
AUDIT_SERVICE_URL	Yes	http://claw-audit-service:4007
OLLAMA_SERVICE_URL	Yes	http://claw-ollama-service:4008
HEALTH_SERVICE_URL	Yes	http://claw-health-service:4009
IMAGE_SERVICE_URL	Yes	http://claw-image-service:4012
FILE_GENERATION_SERVICE_URL	Yes	http://claw-file-generation-service:4013
AGENT_SERVICE_URL	Yes	http://claw-agent-service:4015
RESEARCH_SERVICE_URL	Yes	http://claw-research-service:4016
WORKSPACE_SERVICE_URL	Yes	http://claw-workspace-service:4014
PAYMENT_SERVICE_URL	Yes	http://claw-payment-service:4018
PLUGIN_SERVICE_URL	Yes	https://plugin-service:4021

---

Per-Service Port Variables

Variable	Default	Service
AUTH_PORT	4001	Auth
CHAT_PORT	4002	Chat
CONNECTOR_PORT	4003	Connector
ROUTING_PORT	4004	Routing
MEMORY_PORT	4005	Memory
FILE_PORT	4006	File
AUDIT_PORT	4007	Audit
OLLAMA_SERVICE_PORT	4008	Ollama Service
HEALTH_PORT	4009	Health
CLIENT_LOGS_PORT	4010	Client Logs
SERVER_LOGS_PORT	4011	Server Logs
IMAGE_PORT	4012	Image
FILE_GENERATION_PORT	4013	File Generation
AGENT_PORT	4015	Agent
RESEARCH_PORT	4016	Research
WORKSPACE_PORT	4014	Workspace
PAYMENT_SERVICE_PORT	4018	Payment
PLUGIN_SERVICE_PORT	4021	Plugin

---

Per-Service Database URLs

Prisma reads from DATABASE_URL per service. Each service's .env or the root .env sets a namespaced variable:

Variable	Service
AUTH_DATABASE_URL	Auth
CHAT_DATABASE_URL	Chat
CONNECTOR_DATABASE_URL	Connector
ROUTING_DATABASE_URL	Routing
MEMORY_DATABASE_URL	Memory
FILES_DATABASE_URL	File
OLLAMA_DATABASE_URL	Ollama Service
IMAGES_DATABASE_URL	Image
FILE_GENERATIONS_DATABASE_URL	File Generation
AGENT_DATABASE_URL	Agent
RESEARCH_DATABASE_URL	Research
WORKSPACE_DATABASE_URL	Workspace
PAYMENT_DATABASE_URL	Payment
PLUGIN_DATABASE_URL	Plugin
AUDIT_MONGODB_URI	Audit
CLIENT_LOGS_MONGODB_URI	Client Logs
SERVER_LOGS_MONGODB_URI	Server Logs

---

Workspace OAuth Credentials

Variable	Required	Description
GITHUB_CLIENT_ID	No	GitHub OAuth app client ID
GITHUB_CLIENT_SECRET	No	GitHub OAuth app client secret
GITLAB_CLIENT_ID	No	GitLab OAuth app client ID
GITLAB_CLIENT_SECRET	No	GitLab OAuth app client secret
SLACK_CLIENT_ID	No	Slack app client ID
SLACK_CLIENT_SECRET	No	Slack app client secret
JIRA_CLIENT_ID	No	Jira (Atlassian) OAuth client ID
JIRA_CLIENT_SECRET	No	Jira OAuth client secret
GOOGLE_CLIENT_ID	No	Google OAuth client ID (Drive, Gmail)
GOOGLE_CLIENT_SECRET	No	Google OAuth client secret
FIGMA_CLIENT_ID	No	Figma OAuth client ID
FIGMA_CLIENT_SECRET	No	Figma OAuth client secret

---

Research Service

Variable	Required	Default	Description
TAVILY_API_KEY	No	—	Tavily search provider API key
SEARXNG_BASE_URL	No	—	SearXNG instance base URL

---

Dynamic Model Discovery (Ollama service)

Variable	Required	Default	Description
DISCOVERY_AUTO_REFRESH_ENABLED	No	true	Enable background refresh of the Ollama model catalog
DISCOVERY_MAX_RESULTS_PER_SOURCE	No	50	Max catalog entries pulled per discovery source per refresh
DISCOVERY_AUTO_APPROVE_CONFIDENCE	No	0.85	Min classifier confidence for auto-approving new catalog rows

---

Desktop Agent Auth (Phase A — magic-link pairing + device-code + refresh rotation)

Variable	Required	Default	Description
AGENT_ACCESS_TTL_SECONDS	No	900	Access token lifetime for a paired desktop agent session
AGENT_REFRESH_TTL_DAYS	No	30	Refresh token lifetime for a paired desktop agent session
AGENT_PAIRING_TTL_SECONDS	No	120	Window for a user to complete magic-link pairing
AGENT_DEVICE_CODE_TTL_SECONDS	No	900	Device-code authorization request lifetime
AGENT_REFRESH_GRACE_SECONDS	No	15	Grace window allowing the old refresh token after rotation (replay guard)

---

Provider API Keys

Optional — can also be configured through the UI connector management interface.

Variable	Required	Default	Description
OPENAI_API_KEY	No	—	OpenAI API key
ANTHROPIC_API_KEY	No	—	Anthropic API key
GOOGLE_GEMINI_API_KEY	No	—	Google Gemini API key
AWS_ACCESS_KEY_ID	No	—	AWS access key for Bedrock
AWS_SECRET_ACCESS_KEY	No	—	AWS secret key for Bedrock
AWS_REGION	No	us-east-1	AWS region for Bedrock
DEEPSEEK_API_KEY	No	—	DeepSeek API key
GROK_API_KEY	No	—	xAI Grok API key

Notes:

• Keys configured through the UI (connectors) take precedence over environment variables.
• All keys are encrypted at rest with AES-256-GCM when stored via the Connector service.

---

Image Moderation (shared chats)

Variable	Required	Default	Description
GOOGLE_CLOUD_VISION_API_KEY	No	—	Google Cloud Vision SafeSearch key, read by claw-chat-service.

Blank is a safe default, not a broken one. The scan does not decide whether a shared chat is readable — a published share is always readable by link. It decides one thing only: whether that share may additionally carry advertising and be offered to search engines. With no key, images are never cleared, so such a share stays readable and unmonetised.

Getting the key — Google Cloud Console → pick or create a project → APIs & Services → Library → enable Cloud Vision API → Credentials → Create credentials → API key. Restrict it to the Vision API. Billing must be enabled on the project; SafeSearch has a free monthly tier and is charged per image after it.

Unlike the analytics ids below it is read at runtime, so it needs no rebuild — but env_file is consulted only when a container is created, so docker restart will not pick it up either:

./scripts/claw.sh --prod service:recreate chat-service

This is a secret, unlike the analytics ids below. It has no NEXT_PUBLIC_ prefix, is never sent to the browser, and must never be logged — the client that uses it passes it as a query parameter and deliberately keeps it out of every log line (clients/cloud-vision.client.ts).

Only SAFE_SEARCH_DETECTION is requested — no labels, no text, no faces — so a user's shared image is not incidentally run through a general-purpose analysis pipeline. Policy detail: apps/claw-chat-service/CLAUDE.md ("Image moderation gates ads, not the share").

---

Analytics (Google Tag Manager / GA4)

Both are client-side (NEXT_PUBLIC_), so they are baked into the frontend build and are visible to anyone viewing the page — they are public identifiers, not secrets.

Variable	Example	Meaning
NEXT_PUBLIC_GTM_ID	GTM-PPCVCPGM	Container id. Empty disables the tag entirely: no loader, no <noscript> iframe.
NEXT_PUBLIC_GA_MEASUREMENT_ID	G-ABCD1234	Direct GA4 install via gtag.js. Usually empty — a GTM container normally carries the GA4 tag inside it, and setting both double-counts.

A malformed value is treated as unset rather than emitted, so pasting the whole snippet into the variable, or leaving a GTM-XXXXXXX placeholder, ships no tag instead of one that 404s on every page load.

Changing either value requires a frontend image REBUILD, not a restart. Both are passed as Docker build args and inlined by next build, so the value is compiled into the JavaScript that ships to the browser. Editing .env and restarting — or even recreating — the container changes nothing, and the tag goes on being absent with no error anywhere to explain why.

./scripts/claw.sh --prod service:rebuild frontend

In dev the frontend runs next dev and recompiles per request, so service:recreate frontend is enough there. Production is the case that bites.

This is also why a .env edit alone survives no deployment: deploy-prod.sh rebuilds only the services the deployed commit touches, and .env is untracked host state its planner cannot see.

The Content-Security-Policy already names the analytics hosts (constants/analytics.constants.ts feeds content-security-policy.ts). A tag whose host is missing from the policy is blocked with no visible error, which is indistinguishable from analytics never having been installed.

Testing

Variable	Required	Default	Description
USE_MOCK_PROVIDERS	No	false	Use mock provider adapters instead of real APIs

---

Upgrading an existing install

The plugin service added variables (PLUGIN_*, PG_PLUGIN_*, and the bootstrap secret PLUGIN_ENCRYPTION_KEY). An existing .env is never rewritten, so add them by hand. The steps, including how to generate the key and re-issue the certificate, live in the plugin service guide.

---

Generating Secure Values

# JWT_SECRET (64 random characters, base64)
openssl rand -base64 48

# ENCRYPTION_KEY (32 bytes as 64 hex characters)
openssl rand -hex 32

# ADMIN_PASSWORD (strong random password)
openssl rand -base64 24