Tinycloud runs application workloads only on remote Linux/KVM servers. The CLI is a remote client and can run on macOS, Linux, or another development machine, but it never executes the application locally.

​
One-command single-host installation

1

Provision a KVM host

Create a Debian or Ubuntu server with KVM enabled — for example an OVH bare-metal server, or a VPS offering nested virtualization. Verify /dev/kvm exists.
2

Point one DNS record at it

A single A/AAAA record. Apps live on paths below the same hostname, so the minimal setup needs no wildcard DNS and no external OIDC provider.
3

Clone and run the installer

4

Save the one-time CLI token

The script prints it at the end. It is shown once.
The script verifies KVM, installs host dependencies and Node.js, downloads a checksummed Firecracker release and official guest kernel, builds the serving and build rootfs images, generates secrets, configures nginx and Let’s Encrypt and systemd, and bootstraps the organization.

​
What single-host mode gives you

Applications are exposed as https://cloud.example.com/apps/<environment-route>/... using the configured administrator password, so it needs one ordinary DNS record and TLS certificate rather than wildcard DNS or an OIDC registration. The gateway removes the public prefix before forwarding, supplies X-Forwarded-Prefix, and rewrites root-relative Location redirects.
Browser assets should use relative URLs when an app is intended for single-host mode. An absolute /styles.css resolves above the app’s path prefix.

​
Manual and hosted installation

Choose this when you want per-app hostnames and a real OIDC provider.

​
Prerequisites

Linux with /dev/kvm
Node.js 22.18 or newer, and pnpm 10
Firecracker and its matching jailer
cgroups v2, ip, nft, mkfs.ext4, and truncate
A compatible guest kernel and Tinycloud root filesystem
DNS/TLS and an HTTPS broker URL
Either an OIDC application, or local password authentication with a single public URL
Full list with versions in Host requirements.

​
Install and verify the workspace

​
Build the guest image

Follow Guest images, then set the environment described in Server configuration and start the API with its embedded gateway:
Startup fails closed on macOS, when required secrets or authentication are missing, or when the Firecracker image paths are not configured. There is no local runtime fallback — that is deliberate, not a gap.

​
Feature availability after install

SQLite and object storage work with no extra infrastructure. The rest each depend on one operator setting: Confirm what a live target actually offers:

Next: deploy your first app

Bootstrap an organization and ship hello-private.