Tinycloud’s control plane and worker plane run on the same Linux host. The API always selects FirecrackerProvider; it has no local runtime fallback and fails startup on non-Linux hosts.

​
Kernel and virtualization

Linux with KVM exposed at /dev/kvm
cgroups v2
A Linux kernel compatible with Firecracker
Nested virtualization works (a VPS advertising it, for instance), with the performance caveats noted in Observability.

​
Binaries

debugfs matters for a specific reason: handing an untrusted ext4 image to the host kernel would give build code a filesystem parser to attack. The host reads the tar out instead of mounting.

​
Images

  • a compatible guest kernel (vmlinux);
  • a read-only rootfs containing the guest prerequisites;
  • optionally, a build rootfs carrying npm, tar, and git.
Build procedure: Guest images.

​
Permissions

The worker agent must run with permission to:
use KVM
create TAP devices
update nftables
configure jailer cgroups

​
What the guest rootfs must contain

Node.js 22, wget, iptables, setpriv, a UID/GID 1000 worker account, a POSIX shell, and /sbin/tinycloud-init from packages/provider-firecracker/guest. The image builder validates these prerequisites, installs the repository’s init, requires the UID/GID 1000 account, and refuses to overwrite an existing image.

​
Ingress

  • DNS and TLS for one hostname (single-host) or a wildcard (hosted mode);
  • an HTTPS broker URL reachable by the control plane itself;
  • either an OIDC application, or local password authentication with a single public URL.

​
Startup fails closed

pnpm api refuses to start on macOS, when required secrets or authentication are missing, or when the Firecracker image paths are not configured. That is deliberate: a control plane that started with half its isolation configured would be worse than one that did not start.

​
Verifying

Then, from a client:
/v1/ready reports database and runtime-provider readiness. /v1/platform/capabilities reports what a manifest may ask for.