Environment Variables Reference

Environment Variables Reference

All variables are loaded from the .env file in the project root. Copy .env.example to get started.

Server

Variable	Default	Required	Purpose
SERVER_PORT	4454	No	HTTP server listen port
CHANNEL_PORT_RANGE	7701-7799	No	Port range allocated to HTTP/WS/MCP channel runtimes (one port per active channel)
API_URL	http://localhost:4454/api/	Yes	Base URL used internally for self-referencing API calls
FRONTEND_URL	http://localhost:3000/	No	Frontend origin (used for CORS and redirect generation)
ALLOWED_ORIGINS	(empty)	No	Comma-separated list of allowed CORS origins
COOKIE_DOMAIN	(empty)	No	Cookie domain for session cookies (set for multi-subdomain deployments)

Database

Variable	Default	Required	Purpose
MONGODB_URI	mongodb://mongo:27017	Yes	MongoDB connection string
MONGODB_DB	ud	Yes	MongoDB database name

Encryption

flow8 uses NaCl SecretBox with Argon2id key derivation. Both keys must be set and have exact lengths.

Variable	Default	Required	Format	Purpose
ENV_KEY_SALT	(none)	Yes	64 hex chars (32 bytes)	Salt for Argon2 key derivation
ENC_KEY_SECRET	(none)	Yes	256 hex chars (128 bytes)	Secret input for Argon2 key derivation
ENC_KEY_P_N	32768	No	Integer	Argon2 N parameter (memory cost)
ENC_KEY_P_R	8	No	Integer	Argon2 R parameter (block size)
ENC_KEY_P_P	1	No	Integer	Argon2 P parameter (parallelism)
ENC_KEY_LEN	32	No	Integer	Derived key length in bytes

Generate keys:

openssl rand -hex 32   # → ENV_KEY_SALT (64 chars)
openssl rand -hex 128  # → ENC_KEY_SECRET (256 chars)

Authentication

Variable	Default	Required	Purpose
EXTERNAL_JWT_SECRET	(none)	No	JWT HS256 secret for external API token validation
MCP_JWT_SECRET	(none)	No	JWT HS256 secret for MCP server authentication

Microsoft OAuth2

Variable	Default	Required	Purpose
MICROSOFT_CLIENT_ID	(none)	If using MS auth	Azure AD app client ID
MICROSOFT_CLIENT_SECRET	(none)	If using MS auth	Azure AD app client secret
MICROSOFT_SCOPE	offline_access https://graph.microsoft.com/User.Read ...	If using MS auth	OAuth2 scopes requested

Retention Policies

Variable	Default	Required	Purpose
RETENTION_CLEANUP_INTERVAL	2m	No	How often the cleanup job runs (Go duration string: 2m, 5m, 1h)
RETENTION_CLEANUP_BATCH_SIZE	500	No	Max records deleted per cleanup run
RETENTION_DEFAULT_CADENCE	30d	No	Default retention duration for flow executions
RETENTION_DEFAULT_ENTRIES	100	No	Default max execution records to keep per flow
RETENTION_ENFORCED_MIN_FLOWS_ENTRIES	10	No	Minimum execution records that can never be deleted
RETENTION_ENFORCED_MIN_FLOWS_ALL_CADENCE	0	No	Minimum cadence enforced for all-flow retention (0 = no minimum)
RETENTION_ENFORCED_MIN_FLOWS_FILTERED_CADENCE	3d	No	Minimum cadence for filtered-flow retention
RETENTION_ENFORCED_MIN_AUDIT_CADENCE	14d	No	Audit logs are never deleted before this duration

Alert Email

Variable	Default	Required	Purpose
ALERT_EMAIL_FROM	(none)	If using alerts	From address for alert emails
ALERT_EMAIL_HOST	(none)	If using alerts	SMTP host
ALERT_EMAIL_PORT	(none)	If using alerts	SMTP port
ALERT_EMAIL_USER	(none)	If using alerts	SMTP auth username
ALERT_EMAIL_PASS	(none)	If using alerts	SMTP auth password

AI

Variable	Default	Required	Purpose
OPENAI_API_KEY	(none)	If using OpenAI	OpenAI API key for AI modules and flow generation

Capabilities

These flags enable/disable features that depend on native system binaries:

Variable	Default	Purpose
CAPS_STORAGE	true	Enable local file storage
CAPS_SOFFICE	true	Enable LibreOffice document conversion
CAPS_TESSERACT	true	Enable Tesseract OCR
CAPS_MAGICK	true	Enable ImageMagick image processing

Set to false to disable a capability if the binary is not installed.

Output & Display

Variable	Default	Purpose
UNIT_OUTPUT_UI_MAX_BYTES	(unlimited)	Maximum bytes of module output displayed in the UI per field
AUDIT_LOG_FIELD_MAX_BYTES	(unlimited)	Maximum bytes of any single field stored in audit logs (prevents huge payloads)

Application Registration

Variable	Default	Purpose
APPS_AUTOCREATE	true	Auto-register new modules in the apps catalog on startup
APPS_FORCEUPDATE	false	Force re-registration of all modules on startup (useful after module changes)

Docker / Compose (Dev Only)

Variable	Default	Purpose
COMPOSE_FILE	docker-compose.dev.yml	Which compose file to use
DEV_APP_PORT	8000	Host port for app in dev compose
DEV_MONGO_PORT	27017	Host port for MongoDB in dev compose
DEV_MEXPRESS_PORT	8081	Host port for MongoDB Express UI

Build-time (Go Module Access)

Variable	Purpose
GOPRIVATE	Private Go module paths (e.g., git.qix.sx/gorgany/gorgany.git)
GIT_HOST	Git host for private module auth
GIT_USER	Git username
GIT_PASS	Git personal access token
GOPROXY	Go module proxy (use https://goproxy.cn if direct access to proxy.golang.org is blocked)