Configuration Reference
Every environment variable Crow reads, in one place. Crow follows a zero-config-first philosophy: the gateway boots with no .env at all, using the defaults below. Set variables only when you need the feature they unlock.
Configuration lives in .env at the repo root (copied from .env.example by npm run setup). After editing, run npm run mcp-config to regenerate the MCP client config, and restart the gateway.
Day-1 essentials
A brand-new operator usually only ever touches these: CROW_GATEWAY_URL (remote access), MINIO_ENDPOINT + MINIO_ROOT_USER/MINIO_ROOT_PASSWORD (file storage), and one or two integration API keys. Everything else has a working default.
Core (paths, ports, identity)
| Variable | Default | Purpose |
|---|---|---|
CROW_HOME | ~/.crow | Config/data base directory. A second instance on one machine uses its own (e.g. ~/.crow-mpa). |
CROW_DATA_DIR | ~/.crow/data | SQLite data root. |
CROW_DB_PATH | ~/.crow/data/crow.db | Main database file. |
CROW_GATEWAY_PORT / PORT | 3001 | Gateway listen port. |
CROW_GATEWAY_BIND | 0.0.0.0 | Gateway bind address. |
CROW_GATEWAY_URL | (unset = local-only) | Public URL of this instance (e.g. your *.ts.net HTTPS address). Required for remote MCP clients and OAuth. |
CROW_DEVICE_ID | (unset) | Device identity for per-device crow.md overrides (e.g. laptop). |
CROW_FILES_PATH | /home | Root the filesystem MCP server may access (used by npm run mcp-config). |
CROW_JOURNAL_MODE | WAL | SQLite journal mode. Leave alone. |
NODE_ENV | development | Set production on deployed instances. |
Gateway, auth & access
| Variable | Default | Purpose |
|---|---|---|
CROW_DASHBOARD_PUBLIC | false | Escape hatch that lets funneled traffic reach the dashboard. Leave off — the network-exposure invariant depends on it. |
CROW_ALLOWED_IPS | (unset) | Extra CIDR allowlist for dashboard access (e.g. a reverse proxy). |
CROW_SETUP_TOKEN | (unset) | Required token for first-run password setup when set. |
CROW_CSRF_STRICT | enabled | Set 0 only as an emergency CSRF kill-switch. |
CORS_ALLOWED_ORIGINS | (unset) | Comma-separated CORS origin allowlist. |
CROW_ENROLL_ENABLED | 0 | Allow new instance enrollment (pairing). Enable only while pairing. |
CROW_ENROLL_OTC | (unset) | One-time code required for enrollment when set. |
CROW_HOSTED / CROW_HOSTING_API_URL / CROW_HOSTING_AUTH_TOKEN | (unset) | Managed-hosting mode only. |
CROW_CROWDSEC_BOUNCER_KEY / CROW_CROWDSEC_LAPI_URL | (unset) / http://127.0.0.1:8091 | CrowdSec bouncer integration (optional bundle). |
AI & models
| Variable | Default | Purpose |
|---|---|---|
CROW_ORCHESTRATOR_PROVIDER / CROW_ORCHESTRATOR_MODEL | (DB providers table first) | Default provider/model for the orchestrator. Prefer configuring providers in Settings → AI. |
COMPANION_FAST_MODEL | crow-voice/qwen3.5-4b | Fast voice-turn model for the AI Companion. |
COMPANION_ESCALATION_MODEL | crow-chat/qwen3.6-35b-a3b | Escalation model (!escalate / tool turns). |
COMPANION_FAST_DISABLE_THINKING | 1 | Disable chain-of-thought on voice turns. |
COMPANION_TOOL_ESCALATION | 1 | Auto-escalate when tool use is detected. |
COMPANION_TOOL_CONTEXT_LOOKBACK | 8 | Messages scanned for tool intent. |
COMPANION_PORT | 12393 | Companion (Open-LLM-VTuber) server port. |
SDXL_SERVICE_URL | http://127.0.0.1:3005 | Image-generation service for storage tools. |
GPU_IDLE_CHECK_INTERVAL_MS / GPU_IDLE_REVERT_MS | 120000 / 1200000 | GPU orchestrator idle polling / revert window. |
Storage (MinIO / S3)
| Variable | Default | Purpose |
|---|---|---|
MINIO_ENDPOINT | (unset = storage disabled) | MinIO host (or host:port). |
MINIO_PORT | from endpoint | Port override. |
MINIO_ROOT_USER / MINIO_ROOT_PASSWORD | crowadmin / (required) | Credentials. |
MINIO_USE_SSL | false | TLS to MinIO. |
S3_ENDPOINT / S3_ACCESS_KEY / S3_SECRET_KEY | (unset) | Any S3-compatible alternative to MinIO. |
MAX_UPLOAD_SIZE | 104857600 (100 MB) | HTTP upload cap (bytes). |
STORAGE_QUOTA_MB | 5120 | Per-user quota. |
Notifications & push
| Variable | Default | Purpose |
|---|---|---|
NTFY_HOST / NTFY_PORT | localhost / 2586 | ntfy server for phone push. |
NTFY_TOPIC | (unset = disabled) | Topic to publish to. |
NTFY_AUTH_TOKEN / NTFY_EXTERNAL_URL / NTFY_EXTRA_TOPICS | (unset) | Auth, external URL for links, extra topics. |
VAPID_PUBLIC_KEY / VAPID_PRIVATE_KEY | (unset = PWA push disabled) | Web Push keys (npx web-push generate-vapid-keys). |
VAPID_EMAIL | mailto:admin@localhost | VAPID contact. |
RESEND_API_KEY / MPA_EMAIL_FROM / MPA_EMAIL_TO | (unset) | Email notifications via Resend. |
Sharing, P2P & calls
| Variable | Default | Purpose |
|---|---|---|
CROW_UNIFIED_DASHBOARD | enabled | Federated dashboard across paired instances (0 disables). |
CROW_PEER_TOKENS_PATH | per-CROW_HOME | Peer credential file override (multi-gateway hosts). |
CROW_CALLS_ENABLED | 0 | WebRTC calls feature. |
CROW_CALLS_MAX_PEERS | 4 | Max peers per call room. |
WEBRTC_TURN_URL / TURN_SECRET | (unset) | TURN relay for NAT traversal. |
Backup & ops
| Variable | Default | Purpose |
|---|---|---|
CROW_BACKUP_DIR | ~/.crow/backups | Output of POST /api/admin/backup (localhost-only endpoint). |
CROW_BACKUP_KEEP_DAYS | 7 | Retention. |
CROW_BACKUP_TOKEN | (unset) | Extra bearer requirement for the backup endpoint. |
CROW_AUTO_UPDATE | enabled | Pull-based auto-update (0 disables). |
CROW_FILEVIEW_ROOT | home directory | Root the dashboard markdown fileviewer may read. |
CROW_BUNDLES_DIR | ~/.crow/bundles | Installed-bundle directory. |
Advanced / developer
These are intentionally not in .env.example — set them only if you know why: CROW_DISABLE_ROUTER (=1 serves raw per-server tools instead of category tools), CROW_ENABLE_TURBO (=0 disables Turbo Drive), CROW_DEFAULT_SERVER, CROW_SKIP_CONFIRM_GATES, CROW_SYNC_PROVIDERS, CROW_BUNDLE_HOST_ALLOW_ALL, STRICT_PANEL_MOUNT, CROW_PIPELINE_TRACE, CROW_PIPELINE_SUBPROCESS, CROW_REFCOUNT_PATH, CROW_PET_MODE, CROW_PET_SOCKET, BLOG_FIGURE_GATEWAY_URL, BLOG_FIGURE_PYTHON, RENDER_EXTERNAL_URL (legacy Render deploys), CROW_TASKS_DB_PATH, MPA_PROSPECTUS_INBOX/MPA_PROSPECTUS_OUT, JELLYFIN_URL, PLEX_URL, ROMM_PORT, BRAVE_API_KEY (window-manager search). HTTP timeout overrides (in milliseconds, read once at startup): CROW_HTTP_LLM_CONNECT_TIMEOUT_MS (default 20000 — first-byte deadline for streaming LLM), CROW_HTTP_AI_TIMEOUT_MS (default 60000 — total cap for buffered embedding calls), CROW_HTTP_TTS_TIMEOUT_MS (default 10000 — first-byte deadline for TTS synthesis), CROW_HTTP_VOICELIST_TIMEOUT_MS (default 5000 — total cap for voice-list fetches).
Integration API keys
Third-party integration keys (GitHub, Slack, Notion, Google Workspace, Discord, Trello, Canvas, Zotero, …) are documented inline in .env.example with per-service setup links, and on each integration page. Add one at a time; every one is optional.
Bundle variables
Self-hosting bundles (Caddy, AdGuard, Gitea, Vaultwarden, SearXNG, Netdata, Uptime Kuma, …) read their own *_PORT/credential variables, documented in the bundle sections of .env.example and each bundle's manifest.
This page is maintained by hand against the code. If you find a variable in the code that isn't listed here (or one listed that no longer exists), that's a bug — please file it.