EN Configuration

Configuration reference

中文版：配置项速查

Everything lives in backend/.env (a container install passes the same names as environment variables), and backend/.env.example has the full commented list. Values can also be changed at runtime under Settings, and that copy wins: it is stored in the database, so no restart is needed.

Security and sign-in

Variable	Default	Notes
SECRET_KEY	placeholder	Required. Signs login JWTs and is the encryption root for stored secrets. A placeholder or fewer than 32 characters refuses to start. Never change it once there is data.
ADMIN_USERNAME	admin	Account created on first start
ADMIN_PASSWORD	empty	Used only when creating that first account; empty, under 12 characters or a common password refuses to start
LOGIN_MAX_FAILURES / LOGIN_LOCKOUT_MINUTES	5 / 15	Login lockout, counted per account and per source IP, stored in MySQL
TOTP_REQUIRED_ROLES	empty	Roles forced to bind two-factor authentication, for example admin
TOTP_ISSUER	Proxmox Panel	Name shown in the authenticator app
STEP_UP_REQUIRED / STEP_UP_WINDOW_MINUTES	true / 5	Destructive actions require your password again
RATE_LIMIT_ENABLED / RATE_LIMIT_PER_MINUTE / RATE_LIMIT_AUTH_PER_MINUTE	true / 300 / 30	Per-IP request limits for /api/*

Sessions

Variable	Default	Notes
ACCESS_TOKEN_EXPIRE_MINUTES	720	Access token lifetime. Shorter is fine, the frontend refreshes automatically on a 401
REFRESH_TOKEN_EXPIRE_DAYS	14	Refresh token lifetime, i.e. the longest a single login can last. Stored in an HttpOnly cookie
COOKIE_SECURE	empty	Whether the credential cookies require HTTPS. Empty follows FORCE_HTTPS

Web server and proxy

Variable	Default	Notes
HOST / PORT	0.0.0.0 / 8080	Listen address and port
FORCE_HTTPS	false	Plain HTTP is answered with 308 and HSTS (TLS itself is terminated by Nginx / Caddy in front)
FORWARDED_ALLOW_IPS	127.0.0.1	Which sources may set X-Forwarded-Proto. Widening it to 0.0.0.0 lets the public claim to be HTTPS and bypass FORCE_HTTPS
CORS_ORIGINS	http://localhost:5173	Allowed frontend origins, comma separated

Proxmox connection

Variable	Default	Notes
PVE_HOST	empty	Address, without a protocol
PVE_PORT	8006	API port
PVE_TOKEN_ID	empty	Of the form panel@pve!panel
PVE_TOKEN_SECRET	empty	The token's UUID
PVE_VERIFY_SSL	true	Keep it on in production; turning it off exposes the API token to a man in the middle
PVE_TRUST_ENV	false	Whether requests may use HTTP_PROXY / HTTPS_PROXY from the environment. Off by default: Proxmox is usually on the LAN and an inherited corporate proxy turns every call into an inexplicable 502
PVE_CONSOLE_USER / PVE_CONSOLE_PASSWORD	empty	For the console (VNC does not accept a token). Empty disables the console

Database

Variable	Default	Notes
DB_HOST / DB_PORT	127.0.0.1 / 3306	MySQL address and port
DB_NAME	empty	Database name (required)
DB_USER / DB_PASSWORD	empty	Account and password
DB_POOL_SIZE	8	Connection pool ceiling

Monitoring history

Variable	Default	Notes
METRICS_HISTORY_ENABLED	true	Sample node and VM metrics into MySQL
METRICS_SAMPLE_INTERVAL	60	Sampling period in seconds
METRICS_RETENTION_DAYS	30	Retention in days; 0 or negative keeps everything

The two things with no environment variables

• SMTP (mail notifications): configured only under Settings → Mail notifications, covering server, port, encryption, account and password, sender, and the administrator recipient. The password is encrypted with SECRET_KEY before it is stored, the API only reports password_set, and the plaintext never goes back to the browser.
• Proxmox connections: .env supplies only the initial values. Additional connections are maintained under Settings → Proxmox connection, and the panel can hold several.