Twins

A twin is a copy of a production or staging environment for one task: a server of its own in the twins’ project, on production’s release, running your environment from a branch you name. People and coding agents change, break and reset it without affecting production.

What a twin holds

data	where it comes from
seed (the default)	your repository’s .vaicoa/seed.yaml, run once on the empty volume, then a checkpoint
empty	nothing: your application’s own migrations
copy	production’s data, restored and masked by your .vaicoa/mask.yaml, only on purpose

A copy of production needs three things: an owner allows it per production environment from a presence device, with a reason and the environment’s name typed; each copy twin is asked for by a person, or by an agent and approved by a person; the mask Job runs before any unit starts unless the owner waived masking. A copy twin lives at most 24 hours; its links at most 4.

vai twin reset returns a twin to its checkpoint; vai twin reseed runs the seed again.

How you reach it

A twin opens no port to the internet; its firewall allows ICMP only. Its agent holds a tunnel out to the hub, and the hub’s twin proxy serves it:

• with a DNS zone, at task-42.<base> behind one wildcard certificate per hub (one Let’s Encrypt order, ever, instead of one per twin);
• through a grant: a link valid for named addresses (1–8) and a time, redeemed once into a cookie for that name only. The hub opens its own firewall to the grant’s addresses for the grant’s lifetime;
• vai open twin task-42 does all of it in one command.

An unrestricted link (--any) is possible only for a seed twin, from a presence device, for at most 8 hours; never for a copy.

How long it lives

--ttl from 1 to 72 hours (default 4), counted from ready; one extension, never past 72 hours after its creation. An expired twin is deleted by the hub.

Measured

On Hetzner Cloud (stage-2 gate, 20–21 October 2026): a twin ready in 44 s, its address in the hub’s firewall after 11 s, out again 7 s after its deletion. A page through the twin proxy and the tunnel, hub in Nuremberg and twin in Helsinki: median 53 ms for a WebSocket round trip (20 October 2026).