An operator's /
briefing.

Four tiers, plus custom for sales.

Three self-serve sizes and an enterprise escape hatch. App counts below are marketing approximations, not contracts — we enforce the envelope (vCPU/RAM/disk); how many apps fit is the customer's choice.

Two things product should know. Trial isn't a flavor — it's a Hobby VM with upstream metadata. Trial-vs-paying distinction lives entirely in the frontpage; infra never sees billing state. Second: these specific numbers can change (Hobby might become 1 vCPU) without re-opening the design — the shape is settled, the values are tunable.

Four states. That's all.

One paying customer = one workspace = one VM = four possible life states. The third column below is what product needs to know: when a workspace is active, infra doesn't care if the customer is trialing, paying, or a month overdue — that's the frontpage's concern. We only see "run it" or "take it offline".

Four verbs. Safe to retry.

This is the entire transition vocabulary between frontpage and infra. Every call carries a client-supplied request_id; sending the same call twice is safe — we return the same result, never duplicate work. Conflicting in-flight operations get a clear 409 your client can retry on.

Archive is minutes, not instant.

These durations are the contract: "Suspending…" finishes in seconds, "Restoring from archive…" needs to read minutes. Two implications: product messaging must match these ranges, and the frontpage grace-period timers must account for them — don't schedule an archive for 30s before a billing retry fires.

Two off-states. Very different costs.

The customer-visible difference is how quickly we can bring them back when they update their card. Product should map these to your grace-period tiers.

Three pages you own the copy for.

When a workspace isn't running, the customer's URL doesn't 500 — our edge answers directly with a state page. These are three surfaces product/marketing should own the wording and branding of. Each should tell the customer exactly what to do next (pay, restore, contact support).

Your team owns when. Ours owns how.

This is the single most important line in the whole design. The frontpage decides when each transition should happen (grace periods, trial expiries, promo extensions — all yours). Infra decides how it happens (atomicity, ordering, verification, rollback). We don't run billing clocks; you don't run VMs.

Below: the relational model that backs these commitments. Seven tables, one Postgres. Operators call this the "boring-on-purpose" design — every stateful service we have to run at 3am is a liability.

Legend · ◆ primary key · → foreign key · ·pii scrubbed atomically on delete.

Delete means gone. Verified.

When your team calls Delete, we do not mark a column and move on. We verify every step and only report success at the end. This is the GDPR artefact — if a regulator asks, this is what we show them.

Scope of this obligation. Account-deletion decision is frontpage's (whenever the customer clicks the button or legal retention expires). Execution — the actual wipe — is ours. GDPR completeness is our risk to manage.

RPO promise: 24 hours.

Snapshots run every 24 hours by default. If a bare-metal host fails during active use, the customer can lose up to 24 hours of work. Enterprise customers can buy tighter cadence as part of a custom contract — default should stay at 24h to control storage cost.

Scheduling note: host capacity is derived from live workspace assignments, not stored as a counter — so there's no bookkeeping that can drift out of sync with reality. Below is the actual query we run to place a new workspace. Small fleet, cheap query, zero drift risk.

-- find a host in region $1 with room for $2 vcpu / $3 ram / $4 disk
SELECT h.id
FROM hosts h
WHERE h.region_id = $1
  AND h.state = 'healthy'
  AND h.total_vcpu    - COALESCE((SELECT SUM(w.vcpu)    FROM workspaces w WHERE w.host_id = h.id AND w.state IN ('active','suspended')), 0) >= $2
  AND h.total_ram_gb  - COALESCE((SELECT SUM(w.ram_gb)  FROM workspaces w WHERE w.host_id = h.id AND w.state IN ('active','suspended')), 0) >= $3
  AND h.total_disk_gb - COALESCE((SELECT SUM(w.disk_gb) FROM workspaces w WHERE w.host_id = h.id AND w.state IN ('active','suspended')), 0) >= $4
FOR UPDATE SKIP LOCKED
LIMIT 1;

FOR UPDATE SKIP LOCKED lets concurrent schedulers pick different hosts. The workspace INSERT in the same transaction reserves the slot.

gRPC to backends, not browsers.

The control-plane API is not a public API. Three consumers: your frontpage server, our admin tooling, and the host agents. No browser clients, no third-party integrations — those stay on top of whatever you build on the frontpage. This lets us keep one schema/tooling stack for every inbound call, which simplifies the security story considerably.

For your backend team: every mutating call returns an Operation handle immediately. You poll until it's terminal — no wait parameters, no dual sync/async modes. Integrations against this API are, by design, one code path.

Your client only branches on reasons.

Every error from us carries a machine-readable reason. The set is closed and versioned — new reasons are additive; existing reasons never change meaning. Your frontend code never needs a fix because we renamed something. This matters most when you're writing customer-facing error copy on top.

One category your product team should plan for: RESOURCE_EXHAUSTED means "we're at capacity in that region". You need UX for "we can't provision you a workspace right now, try a different region or contact us" — this is not impossible, just uncommon enough that it gets forgotten in mock-ups.

Return an Operation. Callers poll.

Workspace lifecycle

Domain / routing

Operations

Fleet

message Operation {
  string                    id           = 1;
  string                    workspace_id = 2;
  OperationVerb             verb         = 3;  // CREATE · SUSPEND · ARCHIVE · RESTORE · DELETE · RESIZE
  OperationStatus           status       = 4;  // PENDING · RUNNING · SUCCEEDED · FAILED · ROLLED_BACK
  map<string,string>        step_state   = 5;
  string                    error        = 6;
  google.protobuf.Timestamp requested_at = 7;
  google.protobuf.Timestamp started_at   = 8;
  google.protobuf.Timestamp completed_at = 9;
}

Ops integration out of the box.

Three separate layers SRE will care about — Prometheus metrics, OpenTelemetry spans, and an append-only audit log. Nothing custom to wire up.

Metrics · Prometheus :9090/metrics

Tracing · OpenTelemetry

Every API call gets a span; span context propagates into the job runner, so one trace covers the full transition — API call → job start → step execution → completion. Useful when your team asks "why did this customer's archive take 28 minutes?" — SRE can answer in minutes, not hours.

Audit log · survives account deletion

Every transition writes an append-only record. On customer deletion, PII is scrubbed, but the opaque record stays — so we can reconstruct what happened for incident post-mortems without GDPR risk. Legal/compliance should review the audit schema; it's the artefact they'll lean on in any dispute.

Bare-metal, any cloud, through NAT.

Each bare-metal host in our fleet runs a small daemon that dials the control plane and keeps a long-lived session open. Hosts never accept inbound connections from us — they're free to sit in any data center, any cloud, behind any firewall. This is what makes "run our platform on any provider" actually feasible. Hetzner today, OVH tomorrow, on-prem next year — no networking change to the control plane.

Mutual TLS. From day one.

Agents are long-lived, autonomous, and run on hardware we don't always directly control. Bearer tokens are not enough — we use mutual TLS, with our own internal CA issuing per-host certificates bound to a host id and region. Tokens are fine for the frontpage-to-infra call; they're not fine for the infra-to-fleet link.

What this buys us: even if a stolen bearer token leaks, it can't impersonate a host. Even if a host physically disappears (stolen, re-imaged, etc.), retiring it via the admin API cuts it off the fleet immediately — no waiting for cert expiry.

Section 14 originally detailed the command/event stream design (nine command verbs like ProvisionVM, TakeSnapshot; five event types; independent back-pressure on a single mTLS connection). That engineering detail lives in the source spec — it's implementation work the infra team owns. Above is the posture summary.

What we need from you.

Everything above is approved design, pre-implementation. Three categories of open work — where we need decisions, where we accept risk, and what we'll ship first.

Recovery · how we survive disconnects

When a host's connection to the control plane drops and comes back, neither side trusts its state memory. The agent sends an inventory of everything it has on disk; we compare to our database and reconcile differences. Expected but missing → provision again. Orphans (things on the host we don't know about) → alert an operator, never auto-destroy. Stuck in-flight ops get marked failed so upstream can retry. This is what lets us promise that a network blip never leaves a customer's workspace in an inconsistent limbo.

Deferred decisions · needed before build

Explicitly out of scope · needed eventually

Your asks · what we need from the application team