Agent index (llms.txt) — fetch this first, then the page it names.
Node management
These commands run from your computer and manage every node you operate. Your wallet identity (through RootWallet) links you to your nodes: orama node setup records the nodes on your environment, and the cluster records which wallet is the operator.
Prerequisites
- +The RootWallet desktop app running and unlocked
- +Signed in as an operator:
orama auth login - +The environment set:
orama network use mycluster, or pass--env myclusterto each command
List your nodes
orama nodes # nodes in the active environment orama nodes --env mycluster
IP ROLE USER ENVIRONMENT 203.0.113.10 nameserver root mycluster 203.0.113.11 nameserver root mycluster 203.0.113.12 nameserver root mycluster 3 node(s) in mycluster
orama nodes asks the network for the nodes owned by your wallet and falls back to the machines recorded by orama node setup (and, for older setups, a local nodes.conf; see below).
SSH into a node
orama ssh 203.0.113.10 orama ssh 203.0.113.11 --env mycluster
RootWallet provides the key. No SSH key management on your side.
Health
orama status # table: IP, role, status, details orama status --json # for automation orama status --ssh # break-glass: read every node over SSH when no gateway answers
A node is healthy when its gateway answers and its RQLite has settled into Leader or Follower. The data comes from the gateway's operator telemetry API, so it needs a sign-in as an operator. For the numbers behind the verdict use orama status cluster --env mycluster; for one machine you are logged into, sudo orama node status. See Monitoring.
Upgrade your nodes
orama upgrade --dry-run # what each node runs, what it will run, in what order orama upgrade # show the plan, ask, then roll orama upgrade --node 203.0.113.11 --yes
orama upgrade fetches the newest signed release of your network's channel, verifies it, stages it on every node, and restarts the nodes one at a time behind their health and quorum gate. A node with the global layer refreshes it after its own upgrade. See Upgrades. A build of your own goes through orama maint build, orama maint push and orama maint rollout, described there too.
Add a node
orama node setup --ip 203.0.113.13 --password --env mycluster --archive $ARCHIVE \ --base-domain cluster.example.com --join-via root@203.0.113.10
Pass --release, --release-repo and --release-root instead of --archive to install a published release. See Joining nodes.
Change a node
orama edit # a form: choose the node, then its settings orama edit --node 203.0.113.13 --storage-gb 200 --chain-node-id node-13 orama edit --node 203.0.113.13 --exit=true # the node's Tor relay becomes an exit
orama edit changes a node that is already installed, without installing it again, and shows the plan before it acts (--yes skips the question).
| Setting | What it does |
|---|---|
--storage-gb N | Sizes the node's public Kubo for N GB of declared capacity (its StorageMax becomes N plus 10%) and restarts it, and declares the capacity on the chain with MsgDeclareCapacity, signed by your RootWallet through an SSH tunnel to the node's chain. The chain is asked first, after the node, its operator and the bytes deals reserve have been checked: a capacity the node's role bond does not back, or one below what deals reserve, is refused and the node is left as it was. It needs the node's id on the chain (--chain-node-id; orama chain node <id> shows it), or --no-chain to resize the node only |
--exit=true|false | Switches the node's Tor relay between a plain relay and an exit by rewriting only the exit section of its torrc, then restarts the relay. An exit needs a network whose Tor file allows exits. The node's roles on the chain are not changed by this. With --chain-node-id, the edit reads the node's roles from the chain and warns when the relay policy and the chain disagree (an exit relay of a node that holds no exit role, or a plain relay of a node that still holds the exit role and its bond), and says which orama global bond or unbond brings them together; the warning stops nothing. Without it, the edit says the roles were not compared |
--chain-id <id> | The chain id the capacity is signed for, for a network that is on no registry network. A network from the registry names its chain, and the node's chain must be that one: the wallet never signs for the chain a node only says it is on. With no registry network and no --chain-id the edit stops before anything is changed |
--global=true|false | Refused, and the refusal says what does it: the setup flow adds the global layer when it is run again for the node's IP, and orama remove takes a node out. Turning the layer off would drop the validator's consensus key and the node's bonds without retiring either |
The change is made on the node by its own CLI (orama maint global edit), so a node on an older release needs orama upgrade first.
Removing a node
orama remove --node 203.0.113.13 --dry-run orama remove --node 203.0.113.13 orama remove --node 203.0.113.13 --chain-node-id node-13 # also retire it on the chain
It refuses if any Raft group the node votes in would lose quorum, if the node signs for the validator set (--drop-validator removes it anyway), and, for a node with the global layer, until you say what happens to its chain registration (--chain-node-id retires it, --no-chain leaves it). See Joining nodes. To swap a nameserver for a new machine, follow Replace a node.
remove and wipe are different operations, and picking the wrong one is how a deleted VPS ends up still counted toward Raft quorum. remove retires a node from the cluster and then erases it: run it for a node that is or was a member. It works from a survivor, prints what the removal costs every Raft cluster the node votes in (the registry and each namespace it serves), and refuses if any would lose quorum. Every step is keyed on the node and safe to repeat, so a removal that failed part way through is finished by running it again. wipe erases a node and says nothing to the cluster (below). orama node remove is orama remove under its old name and prints a notice that it is replaced.
Wiping a node
wipe erases the target only. Use it for a node that is already retired, that never joined, or to finish a removal whose wipe failed.
orama node wipe --env mycluster --force # every node of the environment orama node wipe --env mycluster --node 203.0.113.13 --force # one node orama node wipe --env mycluster --nuclear --force # also shared binaries, the Tor package and the system accounts
On a cluster member wipe leaves the node a configured Raft voter, keeps its wireguard_peers row applied to every survivor's interface, and keeps its dns_nodes row; remove retires the node from the cluster first. wipe stops the tenant orama-namespace-*@* units before it deletes their data directory. It does not work on OramaOS nodes (no SSH): see OramaOS. The full guide, with what a wipe removes, the manual steps for a machine the CLI cannot reach, and bringing a removed machine back, is Wipe a node.
Push options
orama nodes and orama node list are the same command. push and rollout are maintainer commands, under orama maint.
orama maint push --env mycluster --archive $ARCHIVE # upload from this machine to each node orama maint push --env mycluster --archive $ARCHIVE --node 203.0.113.11 # a single node from the inventory orama maint push --host 203.0.113.14 --archive $ARCHIVE # an installed node not in the inventory yet orama maint push --env mycluster --archive $ARCHIVE --trust-signers 0xYourWallet # nodes installed before archive signing
--direct is accepted and ignored: every push uploads from this machine. Every node verifies the archive before anything under /opt/orama changes (see Signed archives). With no --env, push targets the active environment (orama network current).
On the node itself
These run on a node over SSH, with sudo. Use them instead of raw systemctl: the CLI handles dependency ordering, quorum checks, port availability and health verification.
| Command | What it does |
|---|---|
sudo orama node status | Service status for the node on this machine |
sudo orama node start | Start all services in dependency order |
sudo orama node stop | Stop all services (refuses if quorum would be lost, unless --force) |
sudo orama node restart | Restart all services in order (same quorum check). orama-autoupdate.timer and any run of the update agent already in progress (orama-autoupdate.service) are stopped for the restart; the timer is started again once the node is serving (its first run follows within a few minutes), so the update agent never runs against a node that is down. If the restart fails or the node does not serve, the timer stays stopped, since starting it would run the agent at once against a node that is down, and the output says so and names the command that starts it (systemctl start orama-autoupdate.timer; a reboot starts it too). Ctrl-C, a terminate or a dropped ssh session finishes the restart first (a second Ctrl-C ends the command), then starts the timer if the node serves and otherwise leaves it stopped with the same message |
sudo orama node doctor | Diagnose common problems: services, ports, connectivity, Raft state |
sudo orama node logs <service> [-f] [-n 50] [--since -30min] | Service logs. Aliases: caddy, cluster, coredns, gateway, ipfs, ipfs-cluster, node, olric, rqlite, turn; or a full unit name such as orama-namespace-olric@myapp |
sudo orama node report | All health data as JSON, the collector orama status reads |
sudo orama maint node schema status / apply | Gateway schema migrations against the local RQLite |
sudo orama node invite [--expiry 24h] [--raw] | Mint an invite for a joining node |
sudo orama maint node autoupdate run | Run this node's auto-update agent once (its timer runs it every 15 minutes). See Upgrades |
sudo orama node trust add-root root.json | Adopt a TUF release root on this node, so it accepts releases signed under it |
sudo orama maint global refresh | Bring the global layer's binaries to the staged release and restart the services that run them (orama upgrade runs it) |
sudo orama maint global edit --storage-gb N --exit=true | The node-side step of orama edit |
sudo orama node uninstall | Remove the production services |
A restart of the node holding Raft leadership hands leadership over first and aborts if it cannot. Never stop or restart several nodes at the same time.
How node ownership works
When you set up a node with orama node setup, the CLI authenticates with your wallet, the new node joins with an invite minted for that cluster, and the cluster records your wallet as the operator. orama nodes can then ask the network for "all nodes owned by my wallet". No local file to maintain.
Migrating from nodes.conf
If you have older nodes listed in scripts/nodes.conf, register them with your wallet:
orama maint node migrate-conf --env mycluster
nodes.conf keeps working as a fallback, so you can migrate at your own pace.