Skip to content
VirtConsole Docs

Architecture

VirtConsole has two parts: the panel, which runs on a management server you own, and the agent, a small service you install on each KVM hypervisor. The panel is the only part with a database and a web interface. The agent only executes commands on its host.

                        ┌────────────────────────────┐
                        │      Management server      │
                        │                             │
        Customers ────► │  VirtConsole panel          │
        Admins ───────► │  - admin panel (/admin)     │
        Billing ──────► │  - user panel (/user)       │
                        │  - REST APIs                │
                        │  - database, task queue     │
                        └─────────────┬───────────────┘
                                      │ HTTPS, port 2443
                                      │ (panel initiates, agent answers)
                ┌─────────────────────┼─────────────────────┐
                ▼                     ▼                     ▼
      ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐
      │ Hypervisor       │  │ Hypervisor       │  │ Proxmox VE node  │
      │ node-us-east-1   │  │ node-eu-west-1   │  │ (agentless)      │
      │ KVM + the agent  │  │ KVM + the agent  │  │ Proxmox API      │
      └──────────────────┘  └──────────────────┘  └──────────────────┘

How they talk

Section titled “How they talk”
  • The panel initiates every connection. It sends commands to the agent over HTTPS on port 2443. The agent never needs inbound access to the panel.
  • Each command becomes a task. The agent runs it (create a VM, take a backup, apply firewall rules) and reports progress back. You watch tasks in real time under Tasks in the sidebar.
  • The panel pushes live updates to browsers over a WebSocket connection, so lists and progress bars update without a refresh.
  • A hypervisor and the panel authenticate with a per-hypervisor token that is exchanged during the first handshake and stored encrypted.

Proxmox VE nodes

Section titled “Proxmox VE nodes”

A Proxmox VE node is agentless: the panel talks to the Proxmox API directly instead of installing the agent. You still manage it from the same Infrastructure > Hypervisors screen. See Add a Proxmox VE node.

Where things live

Section titled “Where things live”
  • On the management server: the database (users, plans, IPs, tasks), the web panels, the APIs, billing logic and the task queue.
  • On each hypervisor: the agent, VM disk files in the storages you define, and the network configuration (bridges, NAT) for its instances.
  • Object storage runs on separate S3 servers you register with the panel. See Object storage.

Key rules

Section titled “Key rules”
  • One panel manages many hypervisors. A hypervisor belongs to exactly one panel.
  • Every long-running operation is a task with progress tracking; nothing happens silently in the background.
  • Plans deploy into hypervisor groups. The panel picks an available hypervisor from the group at deploy time.
Section titled “Related”