Skip to content
Vaicoa
Alpha: for testing only; it does not yet meet the Cyber Resilience Act’s requirements. Status and limits →

Architecture

Each customer runs one hub in their own Hetzner project. The hub holds the desired state of every server, creates servers with the customer’s token, runs twins and backups, and serves the team’s devices and coding agents. An agent on every server carries out what the hub holds for it, over connections the server opens.

Reached outboundVaicoa release channelyour Git repositoryYour machinevaithe command, device keycoding agentvai --agent, ownpaas-mcpbrowserthe hub's portal, a twinHub's server · your projectvaicoa-hubadmin plane: portal · API · MCP, in WireGuard onlyagents' door · twin proxydesired state and audit · SQLiterollouts · twins · recovery testsLitestream beside it: a continuous replicaone Go binary, one SQLite fileHub's project · private networkPodman hostproductionPodman hoststagingeach runs vaicoa-agent and your environment from Git, under Podmank3s cluster · laterTwins' projecttwin of an environmentvaicoa-agent · seed data · no open portObject Storagethe hub's replica,the servers' backupsHetzner Cloud APIservers · networks ·firewalls · DNSvaicoa-iaasthe same API elsewhere;KubeVirt provider builtWireGuardagent keysigned requeststunnel, outboundsigned releasesfetches the branchreplicayour tokenor
The running system: one hub per customer. The two petrol arrows are the hub's two doors: people come in through a WireGuard tunnel with a device key, servers come in with signed requests. Nothing on a production server or a twin listens for the hub; every connection starts on the server's side. The hub needs Vaicoa's release channel only to fetch new releases. The dashed k3s box is not built in the alpha.

Five paths through the system

Section titled “Five paths through the system”
  1. Setting up. vai up makes the image, the network, the firewall and the primary IP in your project, creates the hub’s server, installs vaicoa-hub and pairs your device as the owner. Then it closes SSH. From then on the admin plane listens only inside a WireGuard tunnel. See create a hub.
  2. Running servers. The hub keeps the desired state of every server and environment in SQLite. It fetches your environment’s branch from Git every minute. vaicoa-agent on each Podman host asks the hub’s agents’ door for its state with signed requests, applies it and reports back. The hub creates servers through the Hetzner Cloud API with your token, and opens its own firewall for each grant. See your first environment.
  3. Twins. A twin is a copy of an environment in the twins’ project, with seed data by default. Its agent holds a tunnel out to the hub. A person or a coding agent reaches the twin through the hub’s twin proxy with a grant; the twin opens no port. See twins.
  4. Updates. The hub fetches signed releases from Vaicoa’s release channel and records every step in the audit. Security releases reach twins and staging first and production 3 days later; feature releases wait for you to promote them. See releases and updates.
  5. Backup and recovery. Litestream replicates the hub’s database to your bucket as it changes. A new server restores the hub from that replica with the recovery key. The hub runs recovery tests of production servers on throwaway servers. See backups and recovery tests.

What it does not show

Section titled “What it does not show”
  • k3s clusters: built in the agent, refused by the hub’s alpha. The alpha builds Podman hosts only. See status and limits.
  • Other platforms: vaicoa-iaas offers the Hetzner Cloud API for them. The KubeVirt provider is built; the Hetzner passthrough and an OpenStack provider are planned.

For concrete set-ups with their servers and costs, see scenarios.