Server configuration

createControlPlane() is a production server entry point. It always selects the Linux Firecracker provider, embeds the authenticated gateway, and refuses insecure development defaults.

TINY_MODE and TINY_ALLOW_DEV_LOGIN are not supported. There is no development mode and no macOS runtime fallback.

Required configuration

Variable	Meaning
`TINY_TOKEN_SECRET`	platform token-signing seed
`TINY_SECRET_KEY`	envelope-encryption root key
`TINY_SESSION_SECRET`	gateway session and OIDC-state secret
`TINY_BROKER_URL`	public HTTPS control-plane URL used by workloads
`TINY_FIRECRACKER_KERNEL`	guest kernel path
`TINY_FIRECRACKER_ROOTFS`	read-only base rootfs path

Choose one ingress and authentication mode

Single-host
Hosted / wildcard

TINY_PUBLIC_URL=https://cloud.example.com
TINY_LOCAL_AUTH_EMAIL=you@example.com
TINY_LOCAL_AUTH_PASSWORD=…

Apps route below /apps/…. One ordinary DNS record, one TLS certificate, no OIDC registration. This is the default produced by tools/setup-cloud.sh.

TINY_APP_DOMAIN=apps.example.com
TINY_OIDC_ISSUER=https://identity.example.com
TINY_OIDC_CLIENT_ID=tinycloud
TINY_OIDC_REDIRECT_URI=https://control.example.com/_tiny/oidc/callback

Per-app hostnames and a real identity provider. TINY_OIDC_CLIENT_SECRET is optional for public clients and required when the provider expects a confidential client.

A complete hosted example

export TINY_TOKEN_SECRET='replace-with-a-long-random-secret'
export TINY_SECRET_KEY='replace-with-a-different-long-random-secret'
export TINY_SESSION_SECRET='replace-with-another-long-random-secret'
export TINY_APP_DOMAIN='apps.example.com'
export TINY_BROKER_URL='https://control.example.com'

export TINY_OIDC_ISSUER='https://identity.example.com'
export TINY_OIDC_CLIENT_ID='tinycloud'
export TINY_OIDC_REDIRECT_URI='https://control.example.com/_tiny/oidc/callback'

export TINY_FIRECRACKER_KERNEL='/var/lib/tinycloud/images/vmlinux'
export TINY_FIRECRACKER_ROOTFS='/var/lib/tinycloud/images/rootfs.ext4'

pnpm api

Server options

Variable	Default	Meaning
`TINY_DATA_DIR`	`.tiny/control-plane`	database, artifacts, and instance state
`TINY_API_PORT`	`8787`	control-plane port
`TINY_GATEWAY_PORT`	`8080`	embedded gateway port
`TINY_BIND_HOST`	`0.0.0.0` in production	API and gateway bind address; injected test servers default to `127.0.0.1`
`TINY_FIRECRACKER_BIN`	`/usr/bin/firecracker`	VMM executable
`TINY_FIRECRACKER_JAILER`	`/usr/bin/jailer`	jailer executable
`TINY_FIRECRACKER_UID`	`10000`	jailer UID
`TINY_FIRECRACKER_GID`	`10000`	jailer GID
`TINY_FIRECRACKER_BROKER_PORT`	`8787`	guest destination allowed by host nftables
`TINY_FIRECRACKER_ALLOW_EGRESS`	unset	set to `true` to honour `network.egress.mode: allowlist`
`TINY_EGRESS_RESOLVER`	`1.1.1.1`	the single DNS resolver an egress-enabled guest may reach
`TINY_FIRECRACKER_SERIAL_TELEMETRY`	`true`	mirror guest logs and usage to the VM serial console

Host prerequisites are in Host requirements and the image procedure in Guest images.

The current runtime accepts TypeScript/JavaScript workers, SQLite databases, and object storage with no additional resource infrastructure. Postgres, build commands, and direct egress each need one setting below.

The 512 MiB floor

Guest memory is raised to a floor of 512 MiB however little a manifest asks for.

Below roughly 256 MiB the Node runtime’s text pages no longer fit in the guest page cache, and the guest kernel spends its whole CPU quota re-reading them from the virtio disk. On a nested-KVM host a 128 MiB guest read ~280 MB/s while idle and answered no request within two minutes.Firecracker faults guest memory in lazily, so a ceiling the app never touches is not charged to the host.

Databases

Every deployment with resources.database gets durable storage that outlives the microVM, and no credential inside it. SQL travels from the guest to the control plane’s data service over the VM’s private link, authenticated by the deployment’s own workload token. engine: sqlite needs no configuration: one file per environment under $TINY_DATA_DIR/databases, snapshot with VACUUM INTO. It is durable and correct, but it is one writer per database — the data service admits a single open write transaction per environment and says so rather than deadlocking. engine: postgres requires a cluster. See Postgres.

Object storage

resources.storage needs no configuration. Each namespace is a directory under $TINY_DATA_DIR/storage/<environment>/<name>. See Object storage operations for staging, quotas, and durability.

Builds

build.command runs in a throwaway microVM built from a separate image, with the same jailer, KVM, seccomp, and cgroup story as a serving deployment, plus a firewall hole to the package registry and nothing else.

Variable	Default	Meaning
`TINY_FIRECRACKER_BUILD_ROOTFS`	unset	build image path; builds are unavailable without it
`TINY_BUILD_MEMORY_MIB`	`2048`	build VM memory
`TINY_BUILD_CPU_MILLIS`	`2000`	build VM CPU
`TINY_BUILD_DISK_MIB`	`4096`	build VM disk, which must hold `node_modules`

packages/provider-firecracker/guest/build-build-rootfs ./build-rootfs \
  /var/lib/tinycloud/images/build-rootfs.ext4
export TINY_FIRECRACKER_BUILD_ROOTFS='/var/lib/tinycloud/images/build-rootfs.ext4'

The host also needs debugfs (from e2fsprogs) and tar: the result is read out of the guest’s disk image without mounting it, so an untrusted filesystem is never handed to the host kernel.

Without a build image the platform reports executesBuildCommands: false and tiny plan refuses a manifest with build.command. It never falls back to building on the control-plane host.

Direct egress

network.egress.mode: allowlist is off unless TINY_FIRECRACKER_ALLOW_EGRESS is true, because it is the one setting that lets application code reach the internet without passing through the broker. When it is on, the host resolves each declared hostname once, at deploy time, and pins the resulting addresses into that VM’s own nftables table. The guest cannot widen its allowlist later by answering DNS differently, and a hostname that resolves into a private range is refused outright rather than becoming lateral movement.

Prefer a capability. An app with direct egress holds whatever credential that endpoint needs; an app with a capability holds nothing.

CLI and MCP clients

Variable	Meaning
`TINY_API_URL`	remote control-plane URL, below an explicit `--api` flag
`TINY_TOKEN`	bearer token, below an explicit `--token` flag
`TINY_CONFIG`	credential-file path instead of `~/.tiny/credentials.json`

The MCP server is started with pnpm mcp and reuses the current CLI profile when these variables are absent. Neither client starts a local runtime. The API listens on TINY_API_PORT and the embedded application gateway listens on TINY_GATEWAY_PORT; put TLS/reverse-proxy routing in front of both as needed.

Background work

Task	Interval
Reconcile deployment jobs	250 ms
Drain webhooks	1 s
Expire previews	1 min
Scan residual resources	1 h

Work and leases are durable, so a restarted process resumes queued jobs.

Get started

Build apps

Operate

Server configuration

Required configuration

Choose one ingress and authentication mode

A complete hosted example

Server options

The 512 MiB floor

Databases

Object storage

Builds

Direct egress

CLI and MCP clients

Background work

​Required configuration

​Choose one ingress and authentication mode

​A complete hosted example

​Server options

​The 512 MiB floor

​Databases

​Object storage

​Builds

​Direct egress

​CLI and MCP clients

​Background work

Required configuration

Choose one ingress and authentication mode

A complete hosted example

Server options

The 512 MiB floor

Databases

Object storage

Builds

Direct egress

CLI and MCP clients

Background work