Mainbrella Details Backend Architecture for Idempotent Container Provisioning and Lifecycle Tracking

Mainbrella has published an architectural breakdown of its open-source backend, detailing how the platform prevents state drift, resource duplication, and billing discrepancies when client network responses drop during machine provisioning, according to a technical post shared via Hacker News. The analysis focuses on handling ambiguous boundaries in distributed container management, where retried creation requests can inadvertently launch duplicate instances or corrupt execution state.

To coordinate machine allocation before Linux boots, Mainbrella assigns each account a Cloudflare Durable Object to serve as a persistent coordinator with independent storage, complemented by distinct Durable Objects for each machine slot. The account coordinator enforces strict admission control by serializing reservations for slots, monthly start quotas, and compute allowances using an explicit promise tail. Once an admission decision commits, the lock releases so runtimes can provision and boot concurrently. In platform integration tests with a five-slot Builder account, six concurrent creation requests resulted in five booted machines and one conflict error, validating sequential admission alongside parallel provisioning.

Identity and admission safety are enforced before coordination begins. The system's authentication layer rejects explicitly invalid Bearer tokens even when accompanied by valid session cookies, and internal request builders supply account credentials directly to prevent client spoofing. When requesting a container via POST /containers, clients supply an Idempotency-Key along with configuration parameters. Mainbrella atomically commits the reservation and creation receipt; reusing an active key with modified parameters returns an immediate conflict error.

For dropped connections, pending reservations operate with a 90-second reconciliation window before the coordinator queries runtime state. Retried requests check for existing receipts over a 24-hour retention period, returning active containers without charging an additional start or returning an explicit creation_no_longer_running status if the instance has terminated. Machine readiness requires the guest runtime to execute a uname -a command within 60 seconds against a container booted with an entrypoint of sleep infinity.

Internal lifecycle races are managed using incrementing reservation sequence numbers. Host runtimes persist two high-water marks tracking the newest accepted start and the newest cancellation, rejecting any dispatch at or below those counters. Public machine identifiers combine slot names with a createdAt timestamp calculated as max(now, previousCreatedAt + 1) to eliminate collisions across rapid re-creations or clock skew. Compute usage follows weighted allowances—Lite at one compute unit, Medium at 10, and XL at 28—with unconsumed allocations released only upon verified instance shutdown.

For background tasks, Mainbrella supports managed executions with a 15-minute runtime ceiling, a 1-megabyte output buffer, and a shared pool of four concurrent operations per runtime. If a runtime object restarts unexpectedly, recovery routines mark unfinished tasks as interrupted and destroy the guest generation to prevent unmonitored commands from replaying. Private network traffic targeting *.internal domains is routed through an outbound HTTP interceptor that strips user-supplied ownership headers and injects verified runtime metadata.