Reference
Configuration
Every control-plane environment variable.
The API reads its settings from environment variables, or from .env: /opt/vpspilot/api/deploy/.env on a self-hosted install (apply changes with sudo vpspilot restart), be/.env on a manual one. Names are case-insensitive. The dashboard only needs API_URL. The installer fills in everything you need.
Database
DATABASE_HOSTNAMErequiredPostgreSQL host.
DATABASE_PORT5432PostgreSQL port.
DATABASE_USERNAMErequiredLogin for the VPSPilot database.
DATABASE_PASSWORDrequiredPassword. Special characters are escaped for you.
DATABASE_NAMErequiredDatabase name, for example vpspilot.
Keys
SECRET_KEYrequiredSigns access tokens and keys the hashes of emailed codes.
openssl rand -hex 32.ENCRYPTION_KEYrecommendedEncrypts stored secrets. Generate with
python -m app.encryption generate-key. When empty, a key derived from SECRET_KEY is used.ENCRYPTION_KEYS_PREVIOUSemptyComma-separated old keys, still accepted for decryption during a rotation.
ALGORITHMHS256JWT signing algorithm.
Back up your keys
Without ENCRYPTION_KEY (or SECRET_KEY if you rely on the derived key) the stored secrets, including the backup key, can’t be decrypted. Download the recovery kit from Settings → Security and keep it offline.
Sessions and sign-in
ACCESS_TOKEN_EXPIRE_MINUTES15Lifetime of bearer tokens.
REFRESH_TOKEN_EXPIRE_DAYS30Lifetime of the refresh cookie.
REFRESH_COOKIE_NAMEvp_refreshName of the refresh cookie.
COOKIE_SECUREfalseSet to true in production so the cookie is HTTPS-only.
PASSWORD_RESET_TOKEN_EXPIRE_MINUTES30Lifetime of reset links.
TWO_FACTOR_CODE_EXPIRE_MINUTES10Lifetime of emailed codes.
TWO_FACTOR_MAX_ATTEMPTS5Attempts per code.
TWO_FACTOR_RESEND_COOLDOWN_SECONDS30Wait before another code can be sent.
LOGIN_MAX_FAILED_ATTEMPTS5Wrong passwords before lockout.
LOGIN_LOCKOUT_MINUTES15Lockout duration.
RESEND_API_KEYemptyResend API key. When empty, emails are written to the log instead.
EMAIL_FROMVPSPilot <onboarding@resend.dev>Sender. Use an address on a domain verified with Resend.
EMAIL_OVERRIDE_TOemptySend every email to this address instead, with the real recipient in the subject. For testing.
Agents and monitoring
AGENT_API_URLhttp://localhost:8000The URL agents use to reach the API. It is baked into install commands.
AGENT_HEARTBEAT_SECONDS10Heartbeat interval sent to agents.
AGENT_METRICS_SECONDS15Metrics interval sent to agents.
AGENT_OFFLINE_AFTER_SECONDS35Silence before a server is shown offline.
ENROLLMENT_TOKEN_EXPIRE_MINUTES15Lifetime of enrollment tokens.
METRICS_RETENTION_DAYS7How long raw metric samples (and database samples) are kept.
METRICS_ROLLUP_DAYS90How long hourly metric averages are kept, for 30- and 90-day charts.
ALERTS_EVALUATE_SECONDS30How often alert rules run. 0 disables the background loop, and with it scheduled backups.
Database transfers
ARTIFACTS_DIRdata/artifactsWhere encrypted export and import files wait (a volume in the self-hosted install). Deleted after a day.
MAX_TRANSFER_MB1024Largest export or import file.
URLs
FRONTEND_URLhttp://localhost:3000Dashboard URL, used in email links and as the Google Drive sign-in redirect.
PUBLIC_API_URLemptyPublic https URL for GitHub webhooks. Falls back to AGENT_API_URL when that is https.
CORS_ORIGINS["http://localhost:3000"]JSON list of browser origins allowed to call the API directly.
Dashboard
API_URLhttp://localhost:8000Where the dashboard proxies
/api/*. Read at build and start time.