Twins and recovery tests

A twin is a copy of a production or staging host: the same release and the same environment from Git, on a new server in a second Hetzner project. It exists for one task and is deleted after it.

Create, use, delete

pbx twin create --production web-1 --task task-42 --branch agent/task-42 --ttl 4

• Where: in your twins project, set at pbx up or with pbx twin settings. The hub refuses a twins token that belongs to the production project.
• How long: 4 hours by default, from the moment it is ready; at most 72. pbx twin extend adds hours once.
• How many: at most 3 at once.
• The branch: the twin runs the environment from --branch, or production’s branch when you give none.
• Delete: pbx twin delete task-42, or the hub deletes it when its time is up.

Measured on Hetzner Cloud on 20 October 2026: a twin ready after 44 seconds, its address in the hub’s firewall after 11 seconds, and removed from it 7 seconds after delete.

Where a twin’s data comes from

Mode	The data	When
seed	your seed: one job in pbx/seed.yaml and small files in pbx/seed-files/ under the environment’s path, run once on the empty volume	the default
empty	nothing; your app’s own migrations	when the revision has no pbx/seed.yaml
copy	production’s latest backup, restored, then your mask job pbx/mask.yaml	only when an owner has allowed copies for that environment

After the seed or the mask job, the hub takes a checkpoint. pbx twin reset task-42 returns the twin’s data to it.

A copy of production’s data may contain personal data. An owner allows it per environment, from a device with a person’s presence, after a warning; masking is required unless the owner waives it with a reason. A coding agent can only ask for a copy twin; a person approves. A copy twin lives at most 24 hours. Production never runs a seed job.

Reaching a twin

Tested in a lab, not yet on Hetzner Cloud

Reaching a twin’s web app through the hub, with a name from your own DNS zone, one certificate and short-lived access links, is built and tested in a lab, with a test certificate and without a DNS zone. With a real DNS zone and its certificate on Hetzner Cloud it is not tested yet. Twins are not meant to be public: pbx open twin and pbx twin access give short-lived access (pbx commands).

Recovery tests

A recovery test restores a host’s newest backup onto a new server in the twins project, starts the environment, checks it and writes a report with its times. The server is deleted afterwards. Measured on Hetzner Cloud: 64 and 75 seconds from the start to the deleted server.

Evidence

pbx twin evidence task-42 shows what the hub knows of a twin (its revision, its data mode, its times) with a digest, so a report can point at it.