The control plane owns intent and identity; runtime providers own execution. The boundary between them is RuntimeProvider, and everything above it is written as if the runtime could be a Linux worker host, a microVM, or a customer’s own installation — because eventually it is.

​
Request and deploy paths

Remote clients first upload a bounded content-addressed artifact. Deploy requests persist a deployment plus a leased job and return; a background reconciler resumes those jobs after crashes and switches traffic only after verification.
TinycloudService is the only place that combines authorization, auditing, and state transitions. The CLI and MCP server both use the remote REST API. This keeps an agent and a human from getting different answers to the same request.A product dashboard is not implemented yet.

​
Subsystems

The authoritative JSON Schema lives at schema/tiny.v1alpha1.json and is published for editor completion. Parsing is three stages: a strict YAML subset (no anchors, aliases, tags, or multi-document input), JSON Schema validation, then semantic rules that depend on organization policy.Normalization resolves every default exactly once, and the normalized form is what gets hashed, stored on the revision, and read by every downstream subsystem.
IDs are prefixed ULIDs, so they sort by creation time and read well in logs. Deployment status and app lifecycle are separate state machines with explicit transition tables. Errors always carry a stable code, a human message, agent remediation, and a retryability flag.
Repositories over SQLite. Every organization-scoped read takes an organizationId and filters in the query. State changes and their audit events are written in the same transaction; webhook events go to an outbox drained asynchronously.
Four identity layers stay separate — human, agent, app workload, runtime — and every token carries an audience, so a token minted for one boundary is rejected at another. Secrets are sealed with AES-256-GCM under a key derived per context, so a ciphertext cannot be moved between organizations.
Typed functions returning PolicyDecision (allowed, code, reason) rather than booleans, so the reason reaches the audit log and the caller. Approval rules distinguish production from preview: a preview does not gate on capability approval, which is what makes previews useful to an agent.
  • artifacts — content-addressed store; ignores .git, caches, and anything that looks like a credential, and reports the near-miss.
  • planner — resource diff, migration plan, capability status, approvals, cost estimate, and a digest that makes a stale plan detectable.
  • deployer — walks the state machine, provisions, migrates, deploys a candidate, health-checks, and only then switches the route. Retryable failures retain their current state for idempotent reconciliation.
  • lifecycle — idle recommendations, archive with snapshots, restore, and delete behind a grace window.
  • broker — capability calls, in order.
The only path to a deployed app. Resolves hostname to environment, requires OIDC login, evaluates access, strips forged platform headers, mints a short-lived identity token, wakes sleeping deployments, proxies, then meters and audits.OIDC uses discovery, PKCE, encrypted state, nonce and JWKS verification, plus a browser-bound handoff from the identity callback origin to the app origin.

​
Current implementations and intended replacements

The interfaces those swaps happen behind — RuntimeProvider, ResourceProvider, BuildRunner, ControlPlaneStore, SecretSealer, and TokenIssuer — are the parts designed to outlive the current implementations.
Postgres control-plane storage, KMS integration, artifact signing, object replication, and database replication are not implemented in this repository.

​
The indirection that makes a replaceable VM durable

Applications reach their database through DataService rather than a connection: the guest sends SQL over its private link under its workload token, and the control plane resolves that token to exactly one environment’s binding. That indirection is what lets a replaceable microVM have durable state without ever holding a credential. StorageService is the same indirection for bytes. An app names a storage namespace its manifest declared; the control plane resolves the workload token to that namespace’s binding and hands the operation to an ObjectStore. The current store writes to the host filesystem, so swapping in S3 or R2 means implementing that one interface rather than changing anything an app sees.

​
Linux worker plane

The production worker agent is packages/provider-firecracker. It creates one microVM per candidate deployment, waits for the guest health endpoint, and exposes the guest’s private TAP address to the gateway only after it is ready. Firecracker is always launched through its jailer. The guest artifact lives on an ext4 block device; configuration and secrets are delivered through MMDS and never written into that image. The host creates a /30 TAP network per VM. nftables accepts guest traffic only to the host capability-broker port and drops all forwarding, so SDK policy is backed by a host boundary. Firecracker’s default seccomp filters, KVM, disabled SMT in the VM configuration, cgroup CPU quota, and the jailer’s UID/GID and chroot provide defense in depth.

Firecracker worker plane

The executable host/guest contract.