Status: Accepted · 2026-08-20

​
Context

Tinycloud needs a narrow execution environment for short-lived TypeScript HTTP workers. Depending on a third-party worker platform would leave isolation, recovery, policy enforcement, and unit economics outside the product boundary.

​
Decision

All execution goes through RuntimeProvider: capabilities, plan, reconcile, inspect, route, sleep, wake, destroy, logs, usage. Resource provisioning goes through ResourceProvider. Both are semantic, not a lowest-common-denominator wrapper over cloud APIs. Every implementation must pass runProviderContractTests unchanged. The suite encodes the properties the orchestrator relies on:
idempotency under a stable operation key
adoption after a lost response
atomic route switching
a destroy receipt that names anything it could not remove
The server implementation uses one Firecracker microVM per deployment. Firecracker runs only through its jailer with its default seccomp filters; the host adds cgroup limits and per-VM TAP/nftables policy.
This is the baseline tenant boundary, not an optional future hardening step. There is no macOS or local runtime selection. Tinycloud does not implement a general container scheduler or a custom namespace-based sandbox.

​
Consequences

  • Provider-specific features are only reachable through x-provider escape hatches, which are disabled by default and make portability status visible.
  • capabilities() plus checkCompatibility reject an incompatible manifest before any artifact upload or provider mutation.
  • The Firecracker implementation runs through the same provider contract suite using an injected fake backend without requiring KVM in unit tests; Linux integration tests validate the privileged backend separately.