Agent index (llms.txt) — fetch this first, then the page it names.

What you need to run a cluster

Reference. To join the network, start with Get started. This page is reference for what you need before you install a cluster.

To join a network with machines you rent, run orama setup: it does what the pages below do by hand, for every machine at once, and registers you on the chain. This page and the ones after it are for a cluster of your own: your domain, your build, step by step with orama node setup.

This page lists everything to have in place before you install. The next page, Install a cluster from scratch, is the exact sequence. If you only want to try Orama on a single machine, read One-VPS evaluation.

What a cluster is

A cluster is three or more Linux machines (nodes) that share one replicated registry, one DNS zone and one WireGuard mesh. Everything you deploy lives inside it. Each node runs the same software; nameserver nodes also answer DNS.

You need three nodes for a real cluster: the registry database (RQLite) is a Raft group, and Raft needs a majority to keep working. With two nodes, losing either one stops the cluster, so Orama refuses to create namespaces on two. With one node it works for evaluation but is not highly available.

1. Machines

Three VPSes (or more). For each:

Those are the floors of a cluster node. orama setup also installs the global layer (the chain and public storage) unless you pass --cluster-only; that profile needs 4 vCPUs, 8 GiB of RAM and 80 GiB of free disk plus the storage you offer (--storage-gb, default 50), and setup refuses a machine below it before it installs anything.

Those are floors. A comfortable node is 4 vCPUs, 8 GB of RAM and a 160 GB SSD, because IPFS storage is sized to half of a node's disk and every namespace adds processes.

Interim Ubuntu releases (24.10, 25.04, 25.10) are not supported, because the Tor Project does not publish packages for them and every node installs a Tor client.

How you get the machines does not matter: any provider that gives you root over SSH or a sudo user with a key. orama maint sandbox create can rent five on Hetzner for tests (Sandbox).

Ports

The installer opens these on the machine with ufw. If your provider has a firewall in front of the VPS, you must open the same ports there; ufw on the machine cannot open it.

Nothing else is public. Services other than these listen on the WireGuard overlay only.

2. A domain

The cluster is reached by name. You need a domain whose DNS you can change. The cluster becomes the authoritative nameserver for it, so every deployment, namespace and certificate name under it is answered by your own nodes.

Two ways:

• +A subdomain of a domain you already have (recommended). For example cluster.example.com, delegated from the example.com zone wherever it is hosted. You add NS and glue records in the parent zone. The only choice if the domain is registered with Cloudflare Registrar.
• +A whole registered domain. The records live at the registry and you set them at your registrar.

The exact records and registrar steps are in DNS and nameservers. Pick the name now. It is called the base domain in every command (--base-domain).

3. Your own computer

Everything is driven from your computer. Nothing is typed on the servers.

The orama CLI.

brew install DeBrosDAO/tap/orama
orama version

Debian and Ubuntu packages and tarballs for macOS and Linux are on the releases page.

RootWallet, open and unlocked. The desktop app holds the keys. Orama asks it for SSH keys and signatures; there is no SSH key on disk and no password flag. Install it from RootWallet install. On macOS and Linux only; Windows has no desktop app.

A build to install. Every node runs one signed archive, and you get it one of two ways.

Install a published release. You need no checkout, Go or Zig. orama setup does it for a network the CLI knows: it fetches the newest release of the network's channel and verifies it against the release root the network pins, with nothing to supply. For a cluster that is not on a network of the registry, orama node setup --release <version> fetches the release from a release repository, verifies it against a TUF root you chose to trust, and has your RootWallet sign it as the build your cluster runs. You supply three things, none of which it fetches for you: the version, the repository's https address (--release-repo) and the release signers' root.json (--release-root). The root has to reach you by another road than the repository (the project publishes its SHA-256; check the file against it). Every node adopts the root, which is what lets the cluster update itself later (Upgrades).

Build it yourself. Use a checkout of the Orama repository and a build toolchain on your computer:

git clone https://github.com/DeBrosDAO/orama.git
cd orama/core

Details are in Build and sign.

The OpenSSH client tools. orama node setup needs ssh-keyscan and ssh-keygen to pin the server's host key, ssh for --bootstrap-key and sshpass for --password. It looks for them only in /opt/homebrew/bin, /usr/local/bin and /usr/bin.

The VPS login, stored once per machine. If a VPS has a root password, store it in your RootWallet vault. The CLI never takes a password on the command line:

rw vault add 203.0.113.10

It asks for the username (use root, or whatever you pass as --user) and the password. Then --password on orama node setup is only a switch that reads that entry. Some images have no password login and open with a key you already own; see Joining nodes.

Pre-install checklist

Before the installer runs on a server:

1. +Stop Docker if it is running, and free ports 8080 and 4001. Docker commonly binds 8080 (the IPFS gateway) and can take 4001 (the node's own libp2p port). The installer does not check for port conflicts, so find the holder yourself; stopping Docker is the usual fix: sudo systemctl stop docker docker.socket and disable them. (IPFS's swarm port is 4101, deliberately off 4001.)
2. +Stop any existing IPFS instance.
3. +Stop any other service on port 53 on nameserver nodes. The installer handles systemd-resolved automatically, but bind9, dnsmasq and the like must be stopped by hand.
4. +Be sure the machine is a fresh one. A node that was part of another cluster must be wiped first (Wipe a node).

4. A plan for the first signer

The first archive you install must be signed by the wallet that creates the cluster. That wallet becomes the cluster's operator and the only trusted archive signer. Use the same RootWallet account for orama maint build, orama node setup and orama auth login. Write down which account it is. Losing it is how people lock themselves out of upgrading their own cluster.

Checklist

• + Three machines on a supported OS, with root or sudo, and a public IPv4 each
• + Their firewall allows 22, 51820/udp, 80, 443 and, for nameservers, 53
• + A base domain you can add NS and glue records for
• + orama installed locally; RootWallet unlocked
• + Either a release repository address and its root.json, or a repository checkout with Go, Zig and git
• + The OpenSSH client tools, and sshpass for --password logins
• + rw vault add <ip> done for each password-login machine

Next: Install a cluster from scratch.