ubicloud: an open source cloud control plane written in Ruby

A control plane in Ruby driving machines over SSH

The architecture paragraph in the README is unusually concrete for a cloud project, and it is the part worth reading first. The control plane is a Ruby program that stores its data in Postgres, serves HTTP with Roda, reaches the database through Sequel, handles web authentication with Rodauth, and talks to data plane servers over SSH using net-ssh. Tests are RSpec.

What that tells you is that there is no agent binary to install and no message queue in the path. Ubicloud reaches a server by opening an SSH connection to it, which is also why the self-hosting path starts with an SSH key pair in your environment. The security boundary is the SSH key, and the operational surface is one Ruby web process plus a Postgres database.

The licensing is AGPL-3.0 and the primary language on GitHub is Ruby, both consistent with the README. The repository has no tagged releases at all, which is unusual for infrastructure software and means installation is from `main`. At 12,270 stars, 587 forks and 102 open issues, with the last push on 2026-09-18, it is an active project with a real backlog rather than a weekend experiment.

The tree supports the Ruby story and adds a few things you would not guess from the README. Alongside `cli/`, `routes/`, `model/`, `migrate/` and `spec/` there is a `rhizome/` directory, `sdk/`, `openapi/`, `prog/`, `scheduling/` and `cli-commands/`. There is also `ruby_lsp/`, `mise.toml` and `mise.lock` for development tooling, `.herb.yml` for the HTML templating used by the console, and `package.json` alongside `tailwind.config.js` for the front end. A `vendor/` directory is present too, which tells you dependencies are vendored rather than resolved at boot.

From a clone to a console on localhost:3000

The self-hosting quick start is four commands and one compose file:

git clone [email protected]:ubicloud/ubicloud.git

# Generate secrets for demo
./demo/generate_env

# Run containers: db-migrator, app (web & respirate), postgresql
docker-compose -f demo/docker-compose.yml up

# Visit localhost:3000

The comment on the compose line names three containers, db-migrator, app and postgresql, and the app container covers two roles the README calls web and respirate. The `respirate` name is Ubicloud's own vocabulary for the background work that reconciles the control plane's intent against the machines.

After the console is up you still need hardware. The README is direct about this: the easiest way to build your own cloud is to lease bare metal instances from one of the named providers, Hetzner being the worked example, alongside Leaseweb and AWS Bare Metal. Four environment variables carry the provider credentials, `HETZNER_USER`, `HETZNER_PASSWORD`, `HETZNER_SSH_PUBLIC_KEY` and `HETZNER_SSH_PRIVATE_KEY`, and the README points at Hetzner's robot webservice documentation for creating a user and its rescue system for the install.

That rescue system step is load-bearing and easy to skip. The machine has to be running Ubuntu 24.04 before anything else works. Then each instance is enrolled with one command:

# Enter hostname/IP and provider
docker exec -it ubicloud-app ./demo/cloudify_server

The README notes the script currently handles instances leased from Hetzner, which is a narrower statement than the provider list at the top of the page suggests. Two paths exist for using the result: run the control plane yourself, or skip all of it and use the managed platform at console.ubicloud.com.

Cloud Hypervisor inside Linux namespaces, reached over SSH

Elastic compute is the component the README describes most fully, and the choice of hypervisor is the interesting part. Ubicloud uses Cloud Hypervisor as its virtual machine monitor, and each instance of that VMM is contained within Linux namespaces for further isolation. So the isolation story is two layers: the hypervisor's own device isolation, then namespace containment per instance, on top of a kernel that already has the primitives.

The README is careful about scope here. Elastic Compute is described as the control plane communicating with Linux bare metal servers using SSH, which is a different model from an agent-based cloud. There is no long-lived daemon on the host that maintains a connection; the control plane connects when it needs to act.

One consequence worth planning for appears later in the README. When Ubicloud assigns IPv6 addresses to the VMs it creates, an ISP without IPv6 support will not reach them. The README's advice is to use a VPN or a tunnel broker such as Mullvad or Hurricane Electric's, or alternatively to lease IPv4 addresses from the provider and add them to the control plane. That is a real constraint on the default networking model, and it lands on the reader at the end of the quick start rather than at the start.

The example workloads the README names are also compute-shaped: an ephemeral CI/CD pipeline, which it says it is integrating with via GitHub Actions, and compute or memory heavy test runs. Both are workloads where the instance is short-lived and the portability argument matters more than the service catalog does.

IPsec between machines, nftables at the edge, a namespace per customer

Networking is described in three parts, and each names the Linux mechanism doing the work.

First, the private network between machines is IPsec tunnels, giving an encrypted private environment with dual-stack IPv4 and IPv6 and both public and private networking. Second, firewalls and load balancers are Linux nftables rather than a bespoke datapath, and the README links two blog posts explaining how nftables enables flexible firewall rules and how the load balancer works at no license cost. Third, isolation: each customer's VMs operate in their own networking namespace, so the network boundary between tenants is a kernel primitive rather than a virtual switch configuration.

This is the part of the design where Ubicloud is least likely to surprise you, because it declines to invent infrastructure. The load balancer costing nothing is not a pricing decision but a direct consequence of the mechanism chosen. The per-customer namespace is not a marketing claim about isolation but a statement about where the isolation lives.

The trade is that this is Linux nftables as of the current design, so behavior tracks the kernel's tables and rulesets rather than a cloud-specific API. For someone who already runs Linux networking, that is a feature. For someone porting a cloud-agnostic configuration, the translation work is on them.

The IPv6 caveat from the previous section lands hardest here, since this is the section that establishes the address model. Dual-stack is the design; an IPv4-only ISP is the exception the README asks you to route around with a tunnel broker.

Non-replicated block storage on SPDK, and ABAC instead of IAM roles

Block storage is described with its limitation in the name. Ubicloud uses the Storage Performance Development Toolkit to provide virtualized block storage to VMs, and the component is non-replicated. The README is explicit that snapshots and replication are things SPDK enables in the future rather than features present now, so a volume is local to the machine it lives on.

That is a real architectural commitment, not an oversight, and it is consistent with bare metal being the substrate. Two details from the same paragraph are worth keeping: the data encryption key itself is encrypted following security best practices, and the storage toolkit is a data plane component, which means the control plane never carries volume data.

Access control goes by a different name than most clouds use. Instead of IAM, Ubicloud describes Attribute-Based Access Control, where you define attributes, roles and permissions and assign them fine-grained access to resources. The README links a dedicated architecture document on the ABAC design. ABAC rather than role-based IAM means a policy decision can consider attributes of the request rather than only of the principal, which is the right primitive for multi-tenant isolation, though it is also a different mental model from the policy language most cloud administrators already know.

Taken together, the four documented components are elastic compute, networking with IPsec and nftables, non-replicated block storage on SPDK, and ABAC. That is a small, coherent set covering the parts of IaaS that a bare metal substrate can support well.

The description lists more services than the README documents

The GitHub repository description lists elastic compute, block storage that is non replicated, firewall and load balancer, managed Postgres, K8s, AI inference and IAM services. The README's component list documents elastic compute, networking, block storage and ABAC. Three items in the description have no corresponding section on the front page, and in two cases the tree suggests the gap is narrower than the README implies.

Kubernetes appears in the repository topics and there is a `kubernetes/` directory in the tree, yet the README's What's Next paragraph says a managed K8s service is planned next, alongside a metrics and monitoring service. So both statements can be true at once: there is Kubernetes work in the repository, and the managed product is not shipped. If you are evaluating this as a Kubernetes host, the honest reading is that it is on the roadmap, and the directory is the place to look for how far along it is.

Managed Postgres appears in the description but not in the service list. The README does mention Postgres twice, as the control plane's own datastore and as a container in the demo compose file, which is a different thing from offering managed Postgres as a product to customers. The same pattern applies to AI inference, which appears only in the description.

The scoping statement explains why. The README says AWS offers about two hundred cloud services and that Ubicloud will ultimately implement 10 percent of the services that make up 80 percent of that consumption. That is a deliberate target rather than a shortfall, and the price claim sits inside the same frame: the managed cloud is described as roughly 3x cheaper than AWS for the ephemeral workloads it names.

The resources beyond the README are the ones to read next. `doc/` holds the documentation tree, DEVELOPERS.md covers setup, SECURITY.md and COMMIT_MESSAGES.md are both present, and the README closes by inviting questions through the Community Forum discussions rather than an issue tracker.

Editorial conclusion

Ubicloud is a credible answer to a narrow question rather than a general one, which is its strength. If you have bare metal you already pay for, or an ephemeral CI workload you would rather not rent at AWS prices, the pieces are all named and all real: Cloud Hypervisor for isolation, nftables for firewalls and load balancing, SPDK for block storage, Roda and Sequel for the plane that drives them. The honest limits are in the README's own scoping, 10 percent of the services that carry 80 percent of AWS consumption, and in the gap between the repository description's service list and the four components the README documents. Start with the demo path, which reaches a console on localhost:3000 from a clone and a compose file, and read doc/ and DEVELOPERS.md before pointing it at machines that matter. There are no tagged releases, so pin a commit.

Frequently asked questions

Official sources

1. Issues
2. License: AGPL-3.0
3. Project website
4. README
5. ubicloud/ubicloud on GitHub