Configuration
The portal reads environment variables from portal/.env.local; the backend reads config.toml. Most day-to-day settings live in the portal's UI instead.
Portal — required
| Variable | Meaning |
|---|---|
DATABASE_URL | PostgreSQL connection, e.g. postgres://verlocx:…@host.docker.internal:5432/verlocx. |
VERLOCX_DB_ENCRYPTION_KEY | 32-byte key (base64) that encrypts stored credentials. Back it up; never change it on a running installation. |
ROOT_PASSWORD | Password of the built-in root login (bypasses roles — for setup and emergencies). |
VERLOCX_BACKEND_URL | Where the portal reaches the backend's portal listener, e.g. wss://verlocx_backend:8788/ws/portal. |
VERLOCX_PORTAL_SECRET | The portal's own credential towards the backend. Must equal the backend's portal_secret — at least 24 characters, e.g. openssl rand -hex 32. Never the agents' bootstrap secret. |
VERLOCX_PUBLIC_BASE_URL | The portal's public address. Used to build the agent update URL. |
Portal — optional
| Variable | Meaning |
|---|---|
VERLOCX_VNC_PUBLIC_BASE | Public WebSocket base for the browser console, e.g. wss://verlocx.example.com. |
AGENT_RELEASE_DIR | Folder with the agent build the portal serves for self-updates, plus the release.json you sign offline (see Agent releases). Without a valid signed release.json no update is offered. |
VERLOCX_PLATFORM_VMIDS | VMs (IDs or names, comma-separated) shown in the protected Platform project — the servers Verlocx itself runs on. Alias: VERLOCX_PLATFORM_VMS. |
VERLOCX_PLATFORM_ORG | Organisation that owns the Platform project, if there are several. |
SKIP_DB_MIGRATE | 1 skips the automatic migrations on start. |
MIGRATE_STRICT | 1 stops the start when a migration fails, instead of running on a stale schema. |
NEXT_TELEMETRY_DISABLED | Set to 1 by the start scripts — Verlocx sends no telemetry. |
Clusters, identity providers, templates, quotas, leases, SMTP and feature flags are configured in the portal itself — in Clusters, Identity, Templates, Leases, Flags and each project's Settings — and stored encrypted where they contain secrets.
One key, two names: the same value is
VERLOCX_PORTAL_SECRET in the portal's .env.local and portal_secret in the backend's config.toml. If they differ, the backend answers 401 and the portal logs Unexpected server response: 401.Backend — config.toml
| Key | Default | Meaning |
|---|---|---|
listen | — | Address and port, e.g. 0.0.0.0:8787. |
bootstrap_secret | empty | Optional, legacy shared enrollment secret. Only checked while allow_bootstrap_enrollment is on; an empty value never matches. It opens nothing else. |
allow_bootstrap_enrollment | true | Whether bootstrap_secret may still enroll new agents. VMs cloned by Verlocx enroll with one-time tokens instead. Set it to false once every template uses tokens, then rotate or blank the secret. Already enrolled agents are unaffected. The backend warns at start while it is on. |
portal_secret | — | The portal's credential for its connection and admin calls. Must differ from bootstrap_secret; at least 24 characters. Without it the backend runs in legacy mode and warns at start. |
portal_listen | — | Separate listener for the portal, e.g. 0.0.0.0:8788. Don't publish it — only the portal container reaches it. listen keeps the agent connection and the console relays. |
secret_key_path | server.key | Backend identity (Ed25519 private key). Created on first start. |
public_key_path | server.pub | The matching public key — goes into every agent's backend_pubkey. |
tls_cert_path | cert.pem | TLS certificate for wss (self-signed one is generated if missing). |
tls_key_path | tls.key | Its private key. |
agents_store_path | registered_agents.toml | Enrolled agents and their public keys. |
A complete example
portal/.env.local.env
# databaseDATABASE_URL=postgres://verlocx:[email protected]:5432/verlocxVERLOCX_DB_ENCRYPTION_KEY=base64-32-byte-key# sign-in until directory sign-in is set upROOT_PASSWORD=a-long-random-password# backendVERLOCX_BACKEND_URL=wss://verlocx_backend:8788/ws/portalVERLOCX_PORTAL_SECRET=output-of-openssl-rand-hex-32# public addressesVERLOCX_PUBLIC_BASE_URL=https://verlocx.example.comVERLOCX_VNC_PUBLIC_BASE=wss://verlocx.example.com# agent updates and the Platform projectAGENT_RELEASE_DIR=/app/agent-releaseVERLOCX_PLATFORM_VMIDS=verlocx01Changing secrets
| Secret | How to change it |
|---|---|
ROOT_PASSWORD | Change it and rebuild the portal. Nothing else depends on it. |
VERLOCX_PORTAL_SECRET | Change it in the portal's .env.local and the backend's portal_secret together, then restart the backend and rebuild the portal. |
bootstrap_secret | Better: remove it. Once templates enroll by token, set allow_bootstrap_enrollment = false and blank or rotate it. Already enrolled agents keep working with their own keys. |
| Release key (release.key) | Kept offline, never on the server. To rotate: generate a new one, put the new release_pubkey into every agent's config (a configuration run can do that), then sign with the new key. |
VERLOCX_DB_ENCRYPTION_KEY | Don't change it in place — stored credentials could no longer be read. Re-enter the secrets after a change. |
| Backend key (server.key) | Changing it means every agent's backend_pubkey has to change too. Keep it; move it with the server. |
The portal image contains
.env.local — after any change run docker compose up -d --build verlocx_portal.Next up