RunOS

RunOS turns hardware you own into a managed Kubernetes application platform. Point it at any cloud VM or bare-metal box, even one behind NAT, and you get a place to deploy apps and run managed services, without touching kubectl or writing Kubernetes YAML.

What RunOS is (and is not)

RunOS is a control plane for clusters you own. You bring the nodes: a cloud provider (Hetzner, DigitalOcean, Scaleway, Hyperstack, Lambda Cloud) or your own bare-metal Linux hosts. RunOS installs Kubernetes (currently 1.35), wires up networking and TLS, and gives you a CLI, a web Console, and an API to drive it.

It is not a hosted PaaS. No RunOS-owned compute runs your workloads. You own the nodes, the data, and the bill. RunOS never runs your containers on its own infrastructure.

The two things you do

Everything in RunOS is one of two verbs.

Deploy your apps. Ship your own code. From a local directory: runos deploy reads runos.yaml from the current folder, tarballs the project, and RunOS builds the image inside your cluster. No local Docker, no git required. Or from a commit: runos deploy --sha <sha> --app <id> builds a specific commit through a GitHub or GitLab integration.

Provision managed services. Run the open-source infrastructure your apps need: databases (postgresql, mysql), cache (valkey), object storage (minio), a container registry (harbor), messaging (kafka, rabbitmq), analytics (clickhouse), and AI serving (vllm, ollama, litellm, langfuse). RunOS handles install, config, credentials, and upgrades.

How it works

The RunOS API is the control plane. It holds your account, your clusters, and your desired configuration, and it is what the CLI, Console, and AI assistants all call. It never connects into your clusters.

Agents dial out. Inside each cluster, the cluster agent opens one long-lived, mutually-authenticated (mTLS) link out to the RunOS control plane and holds it. The control plane sends instructions down that link ("build this image", "run this migration", "issue this certificate"); the agent does the work and reports back. Because the connection is outbound, there is no inbound port to open. A cluster behind NAT or a firewall works with nothing exposed.

Desired state vs live state. You tell RunOS what you want. RunOS continuously compares that desired state against what is actually running and reconciles the difference. You declare the target; the platform converges on it.

Slow writes are async. Fast reads return immediately. Anything that takes real work (a deploy, a service add, a node join) returns a jobId and finishes in the background. Watch it with runos follow <jobId> or runos jobs.

Identity and addressing. Every instance gets an OSID: its type plus a short id, like postgresql-bcv4l or traefik-i7r7v. The OSID is also its Kubernetes namespace name, so one instance maps to exactly one namespace. Each instance gets a deterministic host under the cluster domain, all covered by a single wildcard TLS certificate that RunOS keeps issued and renewed.

The system map

One control plane, many agents. The RunOS API decides what should happen; the agents make it happen.

Component	Where it runs	What it does
RunOS API	RunOS control plane	The control plane you call. Holds desired state, dispatches jobs. Never connects into your clusters.
CLI (runos)	Your machine / CI	The primary interface to the RunOS API.
Console	Browser	Web UI for the same operations.
Node agent	Each host	Turns a bare Linux box into a Kubernetes node, manages the VPN mesh, reports health.
Cluster agent	In your cluster	Dials out to the control plane, builds and ships apps, runs migrations, keeps TLS valid.
runostty	In your cluster	Per-user workspace pod: a browser terminal and file API for running commands and AI agents.

Ways to use it

Pick whichever fits the task. They all drive the same RunOS API.

• CLI. runos is the primary tool. Install with curl -fsSL https://get.runos.com/cli.sh | bash, then runos manifest update and runos login.
• Web Console. The same operations in a browser.
• AI assistants via MCP. Drive RunOS from Claude, Codex, Gemini, or OpenCode. Run runos mcp configure <target>; the assistant's required first call is runos mcp bootstrap.
• Declarative runos.yaml. Keep an app's config in a file and deploy it as infrastructure-as-code. runos deploy reads it; runos pull writes a running app's config back to disk.

Defaults worth knowing

RunOS ships sensible development defaults and keeps the production-grade options one setting away. Each is off by default so you turn it on deliberately.

• HA is opt-in. Services and apps start as a single replica. Turn on high availability by picking a multi-replica tier (or raising the replica count): for a database that gives you a primary, streaming standbys, and split read-write/read-only endpoints.
• Backups are opt-in. A new database is not backed up until you turn it on, there is no silent daily job. Point it at an S3-style bucket and RunOS wires up scheduled backups, a retention window, and restore.
• Durable storage is opt-in. The default is fast node-local storage (data lives on one node). Pick a distributed tier for replicated volumes that survive a node failure.
• Apps are public by default. A deployed app gets a public host and certificate out of the box. Set standardHttps: false on a port to keep it private (reachable over the VPN). One field.
• Replica count is fixed, by design. Apps run the count you set, no HPA and no surprise scaling. Default sizing is best-effort: limits only, zero requests, Burstable QoS; set explicit cpu/memory to pin it.

Where to go next

• New here? Run the Quickstart: install, sign in, get a cluster, deploy.
• Learn the model: Core concepts (desired vs live state, OSID, sizing, the control loop, trust tiers).
• Ship your code: Deploy apps.
• Need a database, cache, or queue? Managed services.
• Run the clusters and nodes underneath: Clusters and nodes.
• Day-two operations (jobs, logs, metrics, credentials): Operations.
• The CLI, the MCP server, and runostty: Reference.