Core concepts
Ten minutes here will save you an hour everywhere else. These seven ideas explain most of what the panel does and — more usefully — most of what it refuses to do.
Organisation
Section titled “Organisation”Every resource belongs to exactly one organisation. An organisation is the billing, ownership and isolation boundary: addresses, networks, servers, certificates and domains are all scoped to it, and no API call can reach across that line. Users are members of an organisation with a role; a person may belong to several.
Organisations also carry a short name, which is used to build resource names that stay readable in Proxmox — so an operator looking at the hypervisor can tell which tenant a VM belongs to without consulting the panel.
Region
Section titled “Region”A region is one physical location: a Proxmox cluster, its storage, and its edge router. Regions are independent — a private network, a public address or an image lives in one region and cannot be used from another.
Regions come in two flavours, and the difference matters for security:
- Direct mode. The control plane holds the Proxmox credentials and talks to the hypervisor itself. Simple; suitable when the control plane and the cluster are operated by the same team on the same network.
- Agent mode. A small virtual machine inside the region — the executor agent — holds the Proxmox and edge credentials, and connects outbound to the control plane to ask for work. No inbound firewall hole. The panel never learns the hypervisor password. This is the recommended mode, and the one production runs on.
See Control plane and regions.
Private network and subnet
Section titled “Private network and subnet”A private network is an isolated layer-3 domain — think of it as your own routing table that nothing else can reach. Inside it you create subnets, and each subnet has a tier that decides its posture:
| Tier | Purpose | Internet access |
|---|---|---|
app | Application servers, load balancers, anything that talks to the world | Yes, through a gateway |
data | Databases, internal state | Never — isolated by design, no gateway can be attached |
mgmt | Management, bastions, platform appliances | Yes, through a gateway |
The tier is not a label; it is enforced. Attempting to attach a gateway to a data
subnet is refused by the API. This is the cheapest compliance control in the system: your
database subnet cannot accidentally acquire an egress path because someone clicked the
wrong checkbox.
Two private networks never see each other, even when they share the same gateway.
Public IP
Section titled “Public IP”A public address is allocated to your organisation from a pool, then attached to a server. Allocation and attachment are separate on purpose: an address you have paid for stays yours across rebuilds, and moving a service to a new machine does not change the address your users know.
Addresses are routed, not NAT-ed — the address is configured on the virtual machine itself as a second interface. Your server sees its own public address. See Public IPs.
Intent and truth
Section titled “Intent and truth”This is the idea the whole system is built around.
- Your intent lives in the panel database: “this server should have 4 vCPU”, “this
listener should serve
app.example.com”. - The truth lives in the infrastructure: what Proxmox actually has, what the load balancer VM actually loaded.
The panel reads truth and reconciles it toward intent. It never assumes a write succeeded. This is why resources show states like applying and applied rather than simply flipping to green: the panel is telling you the difference between what you asked for and what it can currently observe.
Read Intent, truth and reconciliation before you file a bug about a status not changing — the answer is usually there.
Anything that touches infrastructure is a job: create a server, attach an address,
build a cluster. The API validates your request, writes the intent and the job, and
returns 202 Accepted with a job identifier — it does not wait for hypervisors.
Jobs are idempotent: running one twice does nothing the second time. They are resumable: a job interrupted halfway is picked up and continues from where the infrastructure actually is, not from a remembered step number. And they are leased: if the machine running a job disappears, another one reclaims it after the lease expires.
See The job model and Asynchronous operations.
Appliances
Section titled “Appliances”Load balancers, gateways and storage nodes are ordinary virtual machines running open-source software — HAProxy, Tailscale, Garage. zone9 calls these appliances, and they follow one rule that is worth internalising:
Configuration is pulled, never pushed. The panel does not open connections to your appliances. Each appliance holds a device identity, asks the panel for its configuration, applies it, and reports back which version it applied. If the panel is down, the appliance keeps running the last configuration it fetched.
Appliances are also locked: no SSH daemon, no login shell, no user accounts. You do not administer them; you describe what you want and they converge. See Appliances and the pull model.