Guardrails for agents

An agent that works through PaaSbox meets limits at two places: in the portal, which decides which operations its key may ask for, and on the node, where pbx-agent runs only a fixed list of operations. This page lists each limit, what it stops and what it does not, so you can decide what an agent may touch.

In progress: not bookable yet

Built in a lab on 2026-10-10: the node’s fixed list of operations, kubeconfigs the portal cannot read, and the firewall in front of the Kubernetes API. In progress The API keys, their scopes, the confirmations through the API, the rate limits and the audit log: written and tested in the portal’s code, not run against a real cluster. Tell me when it opens.

The guardrails

Guardrail	What it stops	What it does not stop	Status
A key per team, with scopes	Calls outside the key’s scopes: an agent sees only the tools they allow. Calls into another team: its clusters answer “not found”.	A scope covers every cluster in the team. There is no key for one cluster: a key that may delete a test cluster may delete production in the same team.	In progress
The creator’s rights	A key never does more than the admin who created it. Every change needs a team admin.	A key an admin created can do what that admin can, within its scopes.	In progress
Typed confirmation	A create, delete, detach or restore without the cluster’s name in confirm.	An agent that knows the name can type it. The portal checks the name, not that a person agreed.	In progress
A fixed list of operations on the node	Anything on the server that is not one of pbx-agent’s operation types: there is no channel for arbitrary commands, and pbx-agent listens on no port. A release whose signature does not verify is refused.	What a kubeconfig allows inside the cluster.	Built in a lab
Kubeconfigs sealed to the agent’s key	The portal, or anyone between, reading the kubeconfig. A second take: it is handed out once, to the key that asked, within 5 minutes.	Use of the kubeconfig by whoever holds the decrypted file, until it expires (10 minutes to 24 hours) or is revoked.	Built in a lab for the browser; In progress for keys
The firewall on port 6443	A kubeconfig used from an address outside the ranges you allowed.	Use from inside the ranges.	Built in a lab
Rate limits	More than 120 calls a minute per key, or more than 20 changing ones.	One destructive call is one call.	In progress
The audit log	Nothing: it records. Every MCP tool call, and every REST call that changes something or hands out a kubeconfig, with secrets left out; refusals for a scope, a role or a confirmation included.	What happens inside the cluster with a kubeconfig is not in it.	In progress

Inside the cluster, the kubeconfig decides

The guardrails above limit the portal’s operations: which clusters an agent may create, delete, restore or detach, which snapshots and upgrades it may start, and that you can see what it did. They do not limit Kubernetes. An agent with an admin kubeconfig can do anything the cluster allows: delete namespaces, read every Secret, start a privileged pod with the host’s processes. In the lab of 2026-10-10 the host commands for the measurements ran exactly that way, through a privileged pod and an admin kubeconfig.

Two Secrets in kube-system matter here. hcloud holds the Hetzner token inside the cluster, and a Hetzner token opens its whole project, read and write. pbx-etcd-s3 holds your bucket’s keys, which k3s reads for every snapshot. An agent with an admin kubeconfig can read both.

So the choices that limit an agent most are made before it starts:

• Which team. A key reaches every cluster of its team. Keep production in a team that an agent’s key does not belong to, and the key cannot reach it at all.
• Which cluster. Give a test agent a throwaway cluster built for the test, not the cluster that carries production. A single-node cluster per stage and per app keeps what an agent breaks in one place. Why isolated clusters for agents.
• Which project. The Hetzner token inside a cluster opens its project. A project that holds only clusters keeps that reach to clusters.
• Which role. A view kubeconfig uses Kubernetes’ view role: it reads workloads, but not Secrets, and it cannot list nodes. Ask for admin only when the agent must change something.
• Which scopes. Leave out k3s:destructive unless the agent creates or deletes clusters.

What PaaSbox never hands an agent

No tool and no endpoint returns your Hetzner project’s token, the in-cluster token, the bucket’s keys or the cluster’s server token. The audit log stores arguments with secret values replaced. A kubeconfig reaches the agent sealed to its own key pair; Security model has what the portal holds.

Not the app catalog’s actions

Agents operating your apps describes typed actions per app, declared in an app’s catalog entry and served as MCP tools in a lab. That is a different mechanism, for operating apps. This page is about the clusters of PaaSbox Clusters.

Give an agent accessA key with only the scopes it needs, connected over MCP or REST, and its audit log.

Why isolated clusters for agentsWhy an agent's change is tested in a cluster built for the test.