Architecture
One server runs Verlocx: a reverse proxy, the portal, the backend relay and PostgreSQL. Guests connect out to it; it connects to your hypervisor and directory.
Components
| Component | Runs as | Does |
|---|---|---|
| Reverse proxy | Traefik container | TLS for the portal; routes the portal and the browser console (/vnc) to the right container. |
| Portal | Next.js container, port 3000 | The web app and REST API. Holds the rules — RBAC, quotas, templates, leases — and runs the scheduler, deployments and configuration runs. |
| Backend | Rust container, ports 8787 (agents, console relays) and 8788 (portal only, internal) | Relay between portal and agents: commands, live status, metrics, deployment progress, console sessions. Proves its identity to agents with an Ed25519 key; accepts the portal only with the portal's own secret. |
| PostgreSQL 16 | On the host, port 5432 | All portal data. Credentials (domain-join account, cluster tokens, SMTP) are stored encrypted with VERLOCX_DB_ENCRYPTION_KEY. |
| Verlocx agent | Windows service in the guest | Identity (rename, domain join, local admins), workflow steps, scripts, metrics, disk scans, self-updates. |
How a VM gets deployed
- A user requests a VM. The portal checks the project's rules (template, size, quota, name, VMID) and stores the request.
- The portal clones the template on Proxmox, gives the clone a unique SMBIOS UUID and starts it.
- On first boot the agent reads that UUID, connects out to the backend and authenticates — the portal now knows which VM it is.
- The portal sends the workflow's guest steps through the backend: rename, domain join (reboots are resumed), local admins, scripts.
- Last, the portal places the VM in its backup job and HA rule. Every step and its timing is visible live on the VM page.
Design principles
- Guests only connect out. No inbound port is opened on a VM for Verlocx.
- Pinned identity. Agents trust exactly one backend key; a different host can't impersonate it.
- The database is the truth. Live hypervisor state is reconciled into it; the UI reads one consistent model.
- Everything is audited. Every change — in the UI or through the API — writes an activity entry.
The exact rules for each connection are in Firewall & ports.
Connection flows
A command to a guest
- A user clicks an action, or a workflow step is due — the portal checks the permission and writes an activity entry.
- The portal sends the command to the backend over its
/ws/portalconnection. - The backend forwards it to the agent of that VM over the agent's own outbound connection.
- The agent runs it locally and reports progress and the result back the same way.
A browser console session
- The user opens the console; the portal asks Proxmox for a one-time console ticket.
- The browser opens a WebSocket to
/vncon the Verlocx server; the proxy hands it to the backend. - The backend relays the session to the node — the user never connects to the hypervisor directly.
Live status in the browser
- Agents report metrics every few seconds; the backend passes them to the portal.
- The portal pushes changes to open browsers as server-sent events — bursts are coalesced so many tabs stay fast.
Security model
- Agents authenticate with their own key after a one-time enrollment, and verify the backend's key on every connection. An enrolled identity can't be taken over: enrolling again with a different key needs the agent offboarded first.
- The portal authenticates to the backend with its own secret, on a separate listener guests can't reach. The agents' bootstrap secret only enrolls agents — a VM can't pose as the portal.
- Users sign in with directory accounts; every action is checked against their roles in that project.
- Secrets — domain-join password, cluster credentials, SMTP — are encrypted at rest and never sent to browsers. The join password reaches only the agent that needs it.
- API keys act with their owner's rights, limited further by scopes and projects.
Availability
Verlocx runs as one portal instance: the scheduler, deployment runners and live updates live in that process. If the server restarts, interrupted deployments are picked up again and interrupted configuration runs are marked as such. Agents simply reconnect. For recovery, back up the database, .env.local and the backend's key files — see Back up and move.
Next up