Skip to content
MZPanel MZPanel
Architecture Control plane, agent dial-out, and the native engine — how data flows through MZPanel.
CtrlK

Architecture

MZPanel has two core pieces: the control plane (cloud) and the agent (on the customer VPS). The agent carries a native execution engine — site, backup, database, Docker and other operations run inside the agent itself.

Connection model — agent dial-out

Section titled “Connection model — agent dial-out”

The agent dials outbound to wss://ws.mzpanel.com:443. The customer VPS opens no inbound ports, needs no domain, and is unaffected by NAT. Each VPS holds one persistent WebSocket carrying:

  • A heartbeat every 30s
  • Status/metrics push (CPU, RAM, disk, site count)
  • Commands from the web → exec → stdout/stderr streamed back
  • Events pushed up (backup done, SSL renewed, …)
[web]  app.mzpanel.com  ──►  api.mzpanel.com  ──ws──►  agent (native engine)  ──►  VPS
                                    ▲                          │
                                    └────────── stream ◄───────┘

Source of truth

Section titled “Source of truth”
  • On the customer VPS: /etc/mz/* — the on-VPS registry. The agent reads and writes it directly; the control plane does not keep its own copy of VPS state.
  • On the control plane: Postgres stores users, orgs, servers (metadata + last-seen), licenses, and the audit log. It does not mirror full VPS state.

Why the public site is separate from the dashboard

Section titled “Why the public site is separate from the dashboard”

This public site (mzpanel.com) is a static Astro build for fast loads, good SEO, and AI/MCP-readable content. The dashboard (app.mzpanel.com) is a separate SPA. See /llms.txt for the machine-readable docs map.