Environment variables

Every variable the code reads is listed. See Configuration for how the pieces fit.

Required

Set these in .env before the first start.

Variable	Used by	Default	Meaning
ENCRYPTION_KEY	compose		64 hex characters (openssl rand -hex 32). Encrypts two-factor secrets, stored S3 credentials, SMTP passwords and plugin secrets. Keep it permanently; replacing it makes them unreadable.
POSTGRES_PASSWORD	compose		Password of the bundled PostgreSQL database. Use URL-safe letters and digits: it is placed inside DATABASE_URL.
WEB_ORIGIN	compose	http://localhost:3000	The exact origin browsers use for the panel. Used for CORS, the Origin check on cookie requests, WebSocket checks and passkeys.

Deployment

Set in .env when your setup needs them.

Variable	Used by	Default	Meaning
API_BIND	compose	127.0.0.1	Host interface the API port (4000) is published on.
API_INTERNAL_URL	compose	http://api:4000	How the panel's server reaches the API to read the appearance settings (name, colours, logo) before a page is sent. The browser uses NEXT_PUBLIC_API_URL. Compose sets this for you; outside Compose it falls back to NEXT_PUBLIC_API_URL.
APP_VERSION	compose	0.9.1.2	The version the panel reports; set by the release you checked out.
GITHUB_REPOSITORY	compose	kavaliersdelikt/fledge	owner/name of the GitHub repository the update checker reads releases from.
GITHUB_TOKEN	compose		Optional fine-grained token with read-only Contents/Metadata access, for private release checks.
NEXT_PUBLIC_API_URL	compose		Browser-reachable API origin. Empty means the panel's host on port 4000. Compiled into the panel image: rebuild after changing.
NEXT_PUBLIC_GITHUB_REPOSITORY	compose		Repository the panel links to for releases (build-time).
TRUST_PROXY	api	1	Behind a reverse proxy: the number of proxy hops (usually 1), or a comma-separated list of proxy addresses or ranges. true trusts every hop. Unset when the API is exposed directly.
WEB_BIND	compose	127.0.0.1	Host interface the panel port (3000) is published on.

Optional seeds

These only seed a form in the panel before it is first saved there; afterwards the database wins.

Variable	Used by	Default	Meaning
ADMIN_IP_ALLOW_DISABLE	api	true	Break-glass: set true to ignore the administrator network allow-list if you locked yourself out.
ALLOWED_IMAGE_PREFIXES	api	itzg/minecraft-server:,itzg/minecraft-bedrock-server:,ghcr.io/lloesche/valheim-server:,node:,python:,oven/bun:,golang:,eclipse-temurin:,php:,ruby:,mcr.microsoft.com/dotnet/	Comma-separated Docker image prefixes templates may use. Seeds the setting in the panel.
BRAND_NAME	api	My Game Hosting	The panel's name before an administrator has saved anything under Settings, Appearance. Afterwards the saved name wins.
BRANDING_DISABLED	api	true	Break-glass: set true to show the built-in Fledge look to everyone and refuse changes under Settings, Appearance, for example after a theme made the panel hard to use. Remove it and restart to change the appearance again. See Recovering from a bad theme.
PLUGIN_REGISTRY_URL	api	https://raw.githubusercontent.com/kavaliersdelikt/fledge/main/plugins/registry/index.json	HTTPS address of the plugin registry index. Empty turns the registry off; bundled plugins always work.
S3_ACCESS_KEY	api		Seeds the object storage form (also used by the bundled SeaweedFS service).
S3_BUCKET	api		Seeds the object storage form before the first save.
S3_ENDPOINT	api		Path-style S3 endpoint. Must be reachable from the API, every node and browsers.
S3_REGION	api	us-east-1	Seeds the object storage form.
S3_SECRET_KEY	api		Seeds the object storage form (also used by the bundled SeaweedFS service).
SMTP_FROM	api	Fledge <fledge@example.com>	Sender, admin@example.com or Fledge <admin@example.com>.
SMTP_HOST	api		SMTP server for invitations, password reset and email notifications.
SMTP_PASSWORD	api		SMTP password (stored encrypted once saved in the panel).
SMTP_PORT	api	587	SMTP port.
SMTP_SECURITY	api	starttls	none, starttls or tls.
SMTP_USER	api		SMTP username.
WEBAUTHN_ORIGINS	api	https://panel.example.com	Comma-separated extra origins allowed for passkeys.
WEBAUTHN_RP_ID	api	panel.example.com	Passkey relying-party id. Defaults to the host of WEB_ORIGIN; set only for unusual setups.

Set by Compose or the image

Normally not edited. Listed for people running the API outside Compose.

Variable	Used by	Default	Meaning
BUNDLED_PLUGINS_DIR	api		Where the bundled plugins are read from; defaults to the copy inside the image.
DATABASE_URL	api		PostgreSQL connection string. Compose builds it from POSTGRES_PASSWORD.
HOST	api	0.0.0.0	Interface the API listens on inside its container.
NODE_ENV	api		production makes cookies Secure; set by the Compose file.
PLUGIN_HOST_URL	api		Address of the plugin host (http://plugins:4020); set by Compose. Empty disables plugins.
PLUGIN_TOKEN_FILE	plugin-host	/run/fledge-plugins/token	Shared bearer token file between the API and the plugin host.
PORT	api	4000	API listen port (plugin host: 4020).
TRANSFER_DIR	api	/var/lib/fledge/transfers	Spool directory for file transfers when object storage is off.
UPDATE_TOKEN_FILE	api	/run/fledge-updater/token	Shared token file between the API and the updater.
UPDATER_URL	api		Address of the updater service; set by Compose.

Node agent

Environment of the fledge-agent service on a node (the connector writes them into the unit).

Variable	Used by	Default	Meaning
ALLOW_INSECURE_HTTP	agent		true allows an HTTP panel URL; local evaluation only.
API_URL	agent		The panel's API address.
CREDENTIAL_FILE	agent	/var/lib/fledge/agent.credential	Where the node credential is stored (mode 0600).
DATA_ROOT	agent	/var/lib/fledge/servers	Where server data lives.
ENROLLMENT_TOKEN	agent		One-time token; cleared from the process after reading.
NODE_ID	agent		The node's UUID.
SFTP_HOST_KEY	agent		Path of the SFTP host key. Defaults to sftp_host_key beside the credential file.
VM_QEMU_USER	agent	libvirt-qemu	QEMU account granted access to managed VM storage.
VM_UEFI_CODE	agent	/usr/share/OVMF/OVMF_CODE_4M.fd	UEFI firmware code image.
VM_UEFI_SECURE_CODE	agent	/usr/share/OVMF/OVMF_CODE_4M.ms.fd	Secure Boot firmware code image.
VM_UEFI_SECURE_VARS	agent	/usr/share/OVMF/OVMF_VARS_4M.ms.fd	UEFI variable template with enrolled trusted keys for Secure Boot profiles. An empty variable store does not enforce Secure Boot.
VM_UEFI_VARS	agent	/usr/share/OVMF/OVMF_VARS_4M.fd	Template for per-VM UEFI variables.

Test switches

Never set these in production. They exist for the test suites.

Variable	Used by	Default	Meaning
FLEDGE_DOCKER_TEST_IMAGE	test		Agent tests only: an image already on the local engine for the live stdin test.
FLEDGE_TEST_ALLOW_LOCAL_FETCH	test		Tests only: lets notification webhooks and plugin registry fetches use local HTTP addresses. Never set in production.
FLEDGE_TEST_CAPTCHA_URL	test		Tests only: address the sign-up bot check is verified against, so tests need no real Turnstile or hCaptcha account. Never set in production.
INSTALL_PLUGIN_WAIT_ATTEMPTS	script		Tests only: how many times install.sh checks the plugin host.
PLUGIN_HOST_NO_LISTEN	test		Tests only: import the plugin host without listening.
PLUGIN_HOST_UNSAFE_TEST_ALLOW_LOCAL	test		Tests only: lets the plugin host reach local HTTP. Never set in production.
PLUGIN_HOST_UNSAFE_TEST_HOST_MAP	test		Tests only: map host names to local test servers.
RATE_LIMIT_AUTH_WRITE	test		Tests only: raises the authentication write rate limit.
SLOW_SWEEP_MS	test		Tests only: interval of the slower sweep (default 60000).
SWEEP_INTERVAL_MS	test		Tests only: how often the API's background sweep runs (default 15000).
UPDATE_POLL_SECONDS	script		Tests only: polling interval of the update scripts.