How it works

PaaSbox Clusters is software that creates small k3s clusters in your own Hetzner project and keeps them current. Three parts do the work: the PaaSbox portal, a small program called pbx-agent on each cluster’s server, and your Hetzner project with your S3 bucket. This page explains how they work together, and why the design keeps the cluster yours.

In progress: not bookable yet (as of 2026-10-10)

What this page describes ran end to end on real Hetzner servers on 2026-10-10, in a lab: a disposable Hetzner project, with the portal running as it would in production. Where a part has not run yet, its status says so. It is not released, and it cannot be booked until the portal is live. Status of each part lists what ran and what has not. Tell me when it opens.

The three parts

The portal is PaaSbox’s web application. Its provisioner holds your Hetzner API token and is the only part that uses it: it creates the cluster’s server, private network, firewall and IP address in your project, and the DNS name of the Kubernetes API, and deletes them again. Its hub answers pbx-agent. Its pages are where you ask for a cluster, a snapshot, an upgrade or a kubeconfig; In progress a REST API and MCP tools give your agents the same requests.

pbx-agent is a program on the server, started by systemd. It is not an AI model. About every 30 seconds it calls the portal over HTTPS, reports the node’s state, and receives two things: what the cluster should look like, and at most one operation. It listens on no port, and the portal never connects to the server. The operations are a fixed list: take a snapshot, restore one, upgrade, issue or revoke a kubeconfig, check the bucket, rotate its own keys, and collect diagnostics once you have allowed it. There is no channel for arbitrary commands.

Your Hetzner project and your bucket hold everything that runs. The server runs Garden Linux with k3s inside the image. Snapshots of the cluster’s state go from the server straight to an S3 bucket you own; they never pass through the portal. Hetzner bills you for the server directly, as for anything else in your project.

How a cluster comes into being

When you create a cluster, the portal works through these steps and shows each one on the cluster’s page:

1. It checks the token and copies the node image into your project. Hetzner keeps an image in one project only, so the first cluster in a project waits for this; later clusters use the copy.
2. It creates the private network, the firewall, the IP address and the DNS name, then the server.
3. The server’s user data holds no lasting secret: only where to download pbx-agent and its checksum, the portal’s address, and an enrollment token that works once and expires after 30 minutes.
4. pbx-agent makes its own keys and enrolls with the token, and the portal checks that the server booted exactly the image of the cluster’s release. pbx-agent receives its configuration, starts k3s and reports when the Kubernetes API answers. Then the cluster is ready.

In the lab run of 2026-10-10 that took 2 minutes 46 seconds on a cpx22, 69 seconds of it the image copy. Create a cluster goes through every field of the form.

How a cluster stays current

The portal holds what each cluster should look like: its release, its add-ons, its snapshot schedule and target, its maintenance window. pbx-agent brings the server to that state and reports when it is there. Three things follow from this:

• Upgrades replace the whole image. The node’s root file system is read-only, so an upgrade takes a snapshot, writes the new release’s image next to the running one, reboots into it and checks that the node is healthy. The data on the server’s disk stays. Every upgrade reboots the node: in the lab the Kubernetes API was down for 34 seconds. Upgrades run at once if you ask, or in your maintenance window In progress. Upgrade a cluster.
• Releases are signed. A release names the image, the k3s version and the add-ons, and is signed with a key that is kept offline. pbx-agent refuses a release whose signature does not verify, and then changes nothing; in the lab it refused a tampered copy. Releases and channels.
• Managed objects are overwritten. The add-ons the portal installs are applied again every 10 minutes, so a change made by hand to one of them disappears. What you deploy yourself is never touched. Choose add-ons.

If the portal cannot be reached, nothing stops: the cluster keeps running, and k3s keeps taking its scheduled snapshots. If pbx-agent is stopped in the middle of an operation, it resumes at the step it was in; in the lab a killed agent did.

Kubeconfigs the portal cannot read

When you ask for a kubeconfig, your browser makes a key pair for that one request. pbx-agent issues a kubeconfig with a token that expires, encrypts it to your browser’s key, and the portal passes it on once; it deletes it after delivery or after 5 minutes. The portal cannot open it. In progress An agent asks the same way through the API, with a key pair of its own. Get a kubeconfig.

What the portal holds

The portal keeps your Hetzner token, the k3s server and agent tokens (k3s’ own tokens, not pbx-agent’s keys), the Hetzner token used inside the cluster, the DNS tokens of the add-ons that need one, and the S3 keys of your snapshot bucket unless you hold them yourself. All of them are stored encrypted, and the secrets it sends to pbx-agent are sealed so that only that cluster’s pbx-agent can open them. It does not hold admin kubeconfigs, pbx-agent’s private keys, your snapshots or your workload data.

Together, the server token and the S3 keys could open a snapshot, and a snapshot contains every Secret in the cluster. If you hold the bucket’s keys yourself, the portal cannot read your snapshots. Security model says what a leaked database or a compromised portal could and could not do.

Who answers for what

PaaSbox Clusters is software you use, not an operations service: nobody watches your cluster for you.

I answer for	You own
The portal and pbx-agent behave as documented	The server, the cluster, its availability and your workloads
A release is tested before it reaches your cluster	The data in your volumes
Operations are safe by default and report their real outcome	The S3 bucket for snapshots, its keys and its lifecycle rules
Safe keeping of your Hetzner token, the S3 keys (if the portal holds them) and the cluster’s server token	The Hetzner bill
	Anything changed by hand on the server

There is no SLA. The cluster runs on one server in your project: if that server fails, your apps are down until it is back, restored from a snapshot, or rebuilt as a new cluster.

If PaaSbox disappears

Your cluster keeps running. pbx-agent only ever called out, so nothing on the server waits for the portal. You have root on the server: the ways in are kubectl debug on the node to add an SSH key, SSH once a key is there, and Hetzner’s rescue system (Get root on the server). The k3s server token is on the server’s disk, and the snapshots are in your bucket. What would go is the DNS name of the Kubernetes API, which lives in PaaSbox’s zone.

You can also leave on purpose, at any time. In progress Detach stops the portal from managing the cluster and stops billing, and the cluster keeps running; its DNS name stays for 30 days. Delete removes everything the portal created for the cluster; the contents of your bucket stay. Detach or delete a cluster and Run without PaaSbox have the steps.

Create your first clusterThe first step of the Learn path: a cluster you keep, and every part of it found again.

Security modelWhat the portal holds, and what a leaked database or a compromised portal could do.