Architecture

dummie splits into a control plane you run once and a fleet of hosts that actually boot the sandboxes. Everything a user or an SDK talks to is the control plane; everything that touches virtualisation happens on a host.

The control plane

A single Go binary, control. It is the whole deployment: the HTTP API, the web console, the OpenAPI document and both sets of database migrations are embedded in it, so there is no asset directory to ship alongside it and no static files to serve from somewhere else.

It owns:

• the API every client uses, at /api/v1
• the console, the web UI at console.<your-domain>
• users, tokens and VM records, in PostgreSQL
• event and telemetry history, in ClickHouse
• user artifacts, in an S3-compatible store

The control plane never runs a guest itself. It decides what should exist and hands that intent to a host.

The hosts

Each machine that boots sandboxes runs dclient, a second binary from the same repository. dclient is the host's agent: it registers with the control plane, receives the work assigned to it, and manages the local services that make a sandbox work.

Those services are:

• proxy — terminates the incoming connection for a guest and hands the file descriptor off to dpipe.
• dpipe — holds that connection open. Because it owns the descriptor rather than proxy, a proxy restart or crash does not drop a live session.
• suricata — runs as a container, watching guest network traffic. Egress policy is enforced per run, not per fleet.
• CoreDNS — resolves names for guests according to that same per-run policy.

The proxy/dpipe split is the part worth understanding: connection lifetime is deliberately decoupled from the lifetime of the process that accepted it, so shipping a new proxy does not disconnect anybody.

The microVMs

A sandbox is a real microVM with its own kernel, not a container. The kernel is built in-tree, stripped to what a short-lived guest needs, which is what makes cold boot fast enough to sit in a request path. Guest root filesystems come from ordinary OCI images, exported to a rootfs at build time.

Hardware isolation is the whole point: a guest gets a full machine — its own kernel, filesystem, and network stack — so code you did not write and cannot trust has nothing to escape into.

Putting it together

                        ┌──────────────────────────┐
  browser / SDK ──────► │  control  (Go binary)    │
                        │  API + console + spec    │
                        └────────────┬─────────────┘
                                     │  assigns work
                         ┌───────────┴───────────┐
                         ▼                       ▼
                 ┌───────────────┐       ┌───────────────┐
                 │ QEMU host     │       │ QEMU host     │
                 │  dclient      │       │  dclient      │
                 │  proxy/dpipe  │       │  proxy/dpipe  │
                 │  suricata     │       │  suricata     │
                 │  ┌─────────┐  │       │  ┌─────────┐  │
                 │  │ microVM │  │       │  │ microVM │  │
                 │  └─────────┘  │       │  └─────────┘  │
                 └───────────────┘       └───────────────┘

The control plane is stateless with respect to guests — it records what should exist, and hosts reconcile toward it. A host that goes silent stops being given work; the VMs it was running are reaped by their TTL.