Architecture

VeilBrowser separates duties across three tiers. Each has one job, which keeps the system auditable and safe to operate.

The three tiers

Separation of duties

• Only workers launch browsers.
• Only the cluster manager orchestrates the fleet and reloads the load balancer.
• Only the cloud control plane owns identity, plans, billing and licensing.

The config-reload pipeline

The cluster manager owns the load balancer's configuration. It is never edited by hand — every change is staged, validated, atomically swapped, and reloaded as an audited operation.

This means a bad configuration can never take down a running load balancer: if validation fails, the live config is left untouched.

How the fleet is addressed

Scale is a replica count, not a mode: every worker serves the same surface, and the load balancer decides which one a launch lands on. Launching is stateless; everything after it is sticky to one worker, so the balancer routes two ways.

• Launch — wss://<hostname>/launch is spread across workers with least_conn, which approximates capacity-aware selection because each live browser is one long-lived CDP connection. A worker at capacity returns 503 before the upgrade and the balancer retries the next one.
• Sticky — /w/<workerId>/… routes deterministically to one worker, so reconnect, VNC and DevTools always reach the box holding that browser. Single domain, single certificate, no wildcard DNS.

Turn it on by setting clusterProxyEnabled on the Cluster row and running Render & Reload. Set VEIL_WORKER_ID on each worker to match its FleetHost hostname, and bound each worker with VEIL_MAX_BROWSERS so overflow routes elsewhere instead of degrading the host it landed on.

How licensing fits

Before launching a browser, a worker calls POST /v1/license/authorize on the cloud control plane. The cloud is authoritative on organization-wide concurrency and plan limits; the worker fails closed if authorize is denied or unreachable. Authorize also reserves the capacity for that launch, and the worker keeps proving its sessions are alive so abandoned ones stop holding your plan. See Licensing & concurrency.

The trust boundary

The tier split above is also a trust boundary, and it is the thing a security review actually asks about. Execution and the software that operates it sit on infrastructure you provision. Commerce, identity and profile records sit in ours.

The asymmetry is deliberate. The material a review usually cares about most — what a browser does and what it stores — is on your side of the line. The commercial record of the account is on ours.

Every connection across the boundary

Five rows. Four of them cross.

Four things worth knowing about those rows:

1. The machine identifier defaults to the host's own hostname when the caller does not supply one. Set VEIL_WORKER_ID deliberately if a hostname is itself sensitive in your environment.
2. The licence check fails closed. If it returns a denial, or cannot complete at all, the launch is refused. There is no local grace mode that lets a browser start while verification is unavailable — plan for that if your workers sit behind an egress policy.
3. The check runs when a launch is requested. It is a gate in front of starting a browser rather than a heartbeat behind one; the liveness reporting that follows only ever releases capacity.
4. Operation records, their logs and fleet snapshots are written to the self-hosted manager's own database and are not sent to us.

Next steps

• Installation
• Operating the cluster
• Edge security & TLS — how the edge behaves at the boundary.
• Security posture — what is not in place, and what exists instead.