Other commands

orama edit [flags]

Change a setting of a node that is already installed, without installing it again.
With no setting flag, in a terminal, it opens a form: choose the node, then the
settings it has. With flags it changes exactly what they name.

  --storage-gb N    the public storage capacity the node offers. The node's public
                    Kubo is sized for N GB (its StorageMax becomes N plus 10%) and
                    restarted, and the capacity is declared on the chain
                    (MsgDeclareCapacity, signed by your RootWallet through an SSH
                    tunnel to a node's chain). The chain refuses a capacity the
                    node's role bond does not back, and one below the bytes deals
                    already reserve; if it refuses, the node is left as it was.
                    The chain needs the node's id there: --chain-node-id (see
                    'orama chain node <id>'), or --no-chain to resize the node only.
  --exit=true|false switch the node's Tor relay between a plain relay and an exit by
                    rewriting only the exit section of its torrc, and restart the
                    relay. An exit needs a network whose Tor file allows exits. The
                    node's roles on the chain are not changed by this.
  --global=...      the global layer cannot be turned on or off here, and edit says
                    what does it: running setup again for the IP adds it, 'orama remove'
                    takes a node out.

The change is made on the node by its own CLI, one node at a time, and the plan is
shown first; --yes skips the question. A node on a release without the node-side
command needs 'orama upgrade' first.

Examples:
  orama edit                                    # The form
  orama edit --node 203.0.113.7 --storage-gb 200 --chain-node-id node-7
  orama edit --node 203.0.113.7 --exit=true --yes

orama maint

Commands for the people who build, release and repair a network. An operator
who joins a network does not need any of them; they are here, out of the way,
and they all work.

  build, push, rollout       build a signed archive and roll it onto a cluster
  inspect, sandbox           check a cluster over SSH; throwaway Hetzner clusters
  invite                     mint an invite for a node to join a cluster
  operator, cluster          the cluster's operator wallets, creators and update policy
  vpn                        a Tor client for an Orama Tor network
  node                       install and stage a node, auto-update, recovery, migration
  global                     validator keys, chain binary staging, the Tor network, tx gate
  network                    publish a network's manifest
  faucet                     set up a test network's public faucet on this node

orama maint build [flags]

Cross-compile all Orama binaries and dependencies for Linux,
then package them into a deployment archive. The archive includes:
  - Orama binaries (CLI, node, gateway, identity, SFU, TURN)
  - Olric, IPFS Kubo, IPFS Cluster, RQLite, CoreDNS, Caddy (built from
    checked-in, checksum-pinned modules; Kubo and RQLite by pinned digest)
  - The global layer, for amd64: oramad (with the orchard verifier linked) and its
    out-of-process verifier orama-orchard-verifier, orama-global and the pinned
    cosmovisor release, which 'orama global install' puts on a node. It needs
    rustup with the x86_64-unknown-linux-musl target, cargo, make and rsync.
    --skip-global-layer leaves it out (a cluster-only archive; arm64 always is).
  - Systemd namespace templates
  - manifest.json with checksums of every file, and manifest.sig

The manifest is signed with your RootWallet (the agent's active account, through
its wallet:sign capability). Nodes install only archives signed by an address in
their trust anchor, /etc/orama/archive-signers, so signing is the default;
--unsigned makes an archive without a wallet signature: the CI build that release
signers sign. A node installs it only when its release root accepted it
('orama maint node stage-archive --release-only'); otherwise it is for local inspection.

--signers rotates the trusted signers: nodes that install this build replace
their list with the given addresses. The build must be signed by a signer the
nodes trust now, and the list must include that signer; retiring a key takes
two builds (the old key adds the new one, the new key then drops the old).

--release-root <root.json> puts a TUF release root in the signed manifest. A node that
installs the build adopts it (/etc/orama/release-root.json) the way it takes a signer
rotation, and from then on accepts releases signed under that root
('orama maint node stage-archive --release-only', the auto-update agent).

The build is reproducible: with SOURCE_DATE_EPOCH set (a release build sets it to
the commit's time) two builds of one commit produce the same archive, byte for
byte. See docs/whitepaper/technical-reference/vol1/29-build-signing-and-release.md, "Reproducible builds".

The resulting archive can be pushed to nodes with 'orama maint push'.

Examples:
  orama maint build
  orama maint build --signers 0xYourWallet,0xNewOperator
  orama maint build --unsigned --output /tmp/inspect.tar.gz

orama maint faucet

orama maint faucet init [flags]

Create the key a node's gateway signs faucet drips with, and print the account
it belongs to. Run it on the node, as root.

The faucet gives test ORAMA to whoever asks (POST /v1/chain/faucet): the gateway
signs MsgFaucet for the recipient with this key and the chain mints the drip.
It exists only on a test network (a chain id with -stagenet-, -devnet- or
-localnet-; the gateway refuses to sign anywhere else), the chain keeps its own
limits (a maximum drip, a cooldown per recipient, a cap per epoch), and it must
be on in the genesis (faucet_enabled).

The key file is created owned by the gateway's account with mode 0600, and an
existing key is never replaced: running init again prints the same account. The
faucet account pays the transaction fee of every drip and mints the drip itself,
so it needs a small balance and nothing more: fund it from the genesis
(chain/scripts/stagenet/deploy.sh does this on stagenet) or from another faucet.

Then turn it on in node.yaml and restart the node:

  chain:
    faucet:
      enabled: true

  orama node restart

orama node upgrade keeps the block. Check it with:

  curl -sS -X POST https://<gateway>/v1/chain/faucet \
    -H 'Content-Type: application/json' -d '{"recipient":"orama1..."}'

orama maint inspect [flags]

SSH into cluster nodes and run health checks.
Supports AI-powered failure analysis and result export.

The report is written to stdout and progress to stderr, so --format json is one
JSON document. A bad flag value (an unknown --subsystem or --format, a timeout
that is not positive) is refused as usage before any node is contacted.

orama maint invite [flags]

Create a single-use invite that lets a new node join the cluster.

The invite names one node of the cluster: its public address, the domain to
present to it, and the fingerprint of the TLS certificate it serves. The
joining node connects to exactly that node and pins exactly that certificate,
rather than resolving the cluster's domain — which reaches any nameserver,
each with a certificate of its own — or trusting whatever certificate it is
first shown. There is nothing else to copy across.

The node is the lowest address the environment's domain resolves to, or the
one named with --node. The token is minted through that node, on the same
connection whose certificate is pinned.

This is the same token as 'orama node invite', which does the same thing from
an existing node instead of from here.

orama maint push [flags]

Upload the pre-built binary archive to nodes and extract it.

The archive is uploaded from this machine to each node in turn: node SSH keys
never leave it, and no node is a hub. --direct is accepted and changes nothing.

--archive names the build: the path 'orama maint build' printed. There is no
default — the newest archive in /tmp may be another checkout's build.

Examples:
  orama maint push --env devnet --archive /tmp/orama-0.200.0-linux-amd64.tar.gz
  orama maint push --env devnet --archive <path> --node 203.0.113.4
  orama maint push --host 203.0.113.4 --archive <path>           # A node not in the inventory yet
  orama maint push --env devnet --archive <path> --trust-signers 0xYourWallet  # Nodes from before archive signing

Each node verifies the archive with its installed orama before anything under
/opt/orama changes: the manifest signature must recover to an address in the
node's /etc/orama/archive-signers and every file must match the manifest.

orama maint release

Cut a release into the DeBros release repository and publish it.

The metadata is TUF, signed with the one release key in your RootWallet. Every
signature is approved by you in the RootWallet desktop app; the command says
what each approval is for before it asks. The release key is listed in the
root for all four roles, so the same wallet signs everything.

  init-root          make the repository's root (once); prints the digest networks pin
  renew-root         the next version of the root, same keys, a new expiry
  cut                list an archive on a channel and sign it (3 approvals)
  refresh-timestamp  re-sign only the timestamp (1 approval)
  publish            upload the archives to GitHub and the metadata to the release host

A channel is nightly, main, or dev/<branch>. cut writes only to the repository
directory (--dir); publish is the step that touches the network, so cut
--dry-run and cut work offline.

orama maint release cut --channel nightly|main|dev/<branch> --archive <path> [flags]

List one or more archives of one version (amd64 and arm64) under a channel and
sign the result: targets.json, then snapshot.json, then timestamp.json, three
approvals in the RootWallet desktop app. Each is announced first. The command
checks that a client would accept the metadata before it writes anything, and
writes only to --dir; it uploads nothing. Run publish to upload.

An archive must be one built with "orama maint build --unsigned" (a release is trusted
through the release root, not a wallet), and an amd64 one carries the global layer.
A version must be dotted numeric (0.3.1) and newer than the channel's newest;
a release is immutable (--replace is for a dev/<branch> build that reuses a version).
Only the newest --retention versions of the channel stay listed. The timestamp
is valid 7 days for nightly and dev, 30 for main.

--dry-run plans the release and stops: nothing is signed, written or uploaded,
and the RootWallet is not contacted.

orama maint release init-root [flags]

Make version 1 of the repository's TUF root: your RootWallet's release public key
for the root, timestamp, snapshot and targets roles, threshold 1, valid for a
year. One approval. Prints the root's SHA-256, the digest network manifests pin
(release_root_sha256), and leaves 1.root.json and root.json in --dir. It refuses
a directory that already has a root.

Today one release key holds all four roles: whoever holds it can sign a root, a
targets file, a snapshot and a timestamp, and it is the only key that can sign
the next root. --keys <file> makes a root that splits the roles when the wallet
can hold more keys, without any other change: a JSON file naming, per role, the
keys (64 hex digits of an ed25519 public key, or "wallet" for your own release
key) and the threshold, for example

  {"root": {"keys": ["wallet"]},
   "targets": {"keys": ["<hex>", "<hex>"], "threshold": 2}}

A role that is left out is your release key at threshold 1. This command signs
the root once, with your key, so your key must be among the root keys and the root
threshold must be 1.

orama maint release publish --dir <dir> [flags]

Upload the last cut or refresh. Before anything is sent the metadata in --dir is
checked as a client would check it, and each archive against the hash the
signed targets name. Then the archives go to the GitHub release for the tag
(created if it is not there; an archive already there is an error), then the
root, targets and snapshot go to the release host with rsync, and the timestamp
last.

Needs gh (logged in, able to upload to the repository) and ssh access to the
release host. --dry-run prints the commands.

orama maint release refresh-timestamp --channel nightly|main|dev/<branch> [flags]

Re-sign the timestamp alone: the next version, naming the snapshot already in
--dir, valid 7 days (nightly, dev) or 30 (main) from now. Clients refuse a
timestamp that has expired, so a repository nobody cuts into needs this before
the last one runs out. Then publish.

orama maint release renew-root [flags]

Make the next version of the root: the same keys, a new year of validity. One
approval. Clients that hold the previous root fetch <N+1>.root.json, verify it
against the root they hold and adopt it, so nobody is handed a new file. Do it
before the root expires; an expired root stops every release.

orama maint rollout [flags]

Full deployment pipeline: build the binary archive, push it to every node,
then upgrade them one at a time.

The rolling upgrade prints its plan — which node holds the raft leadership and
the order the restarts happen in — and stops unless --yes is given.

Examples:
  orama maint rollout --env testnet             # Build, push, then print the plan
  orama maint rollout --env testnet --yes       # Execute the plan
  orama maint rollout --env testnet --no-build  # Reuse the existing archive

orama maint vpn

Join an Orama Tor network from this machine.

A network is described by its tor-network.json file: the directory authorities
and, optionally, the validator onion services it lists. up starts an unmodified
upstream tor on it and offers a SOCKS5 proxy on loopback; check joins the
network and proves a circuit reaches a validator's onion service.

The client has one route: the tor it starts, configured with the network's
authorities and no others. It never falls back to the public Tor network or to
a direct connection. When tor stops, the proxy port closes and whatever was
using it fails; nothing is routed around it. This is a proxy, not a system-wide
tunnel: only applications pointed at the SOCKS port, with names resolved by the
proxy (socks5h), use the network.

Only a private network can be joined: the public Orama network is not launched.

orama maint vpn check [flags]

Start tor on the network (stopped again when the check ends) and read an account
through each validator onion service's tx gate, over a fresh circuit each. The gate
serves only the account read, the broadcast and the tx lookup, so the check uses the
account read; the chain answering "account not found" for the probe address passes.

By default every validator onion service the network file lists is tried, and the check
passes when at least one answers; --onion tries only the one given. It fails when tor
cannot bootstrap on the network's authorities, when none of the onion services answers, and
when the network file lists none and no --onion is given. Nothing is tried outside the
network.

orama maint vpn up [flags]

Start tor on the network and keep it running until interrupted.

The SOCKS5 proxy listens on loopback only (--socks). Point an application at it
as socks5h, so the proxy resolves names, and each distinct SOCKS username gets
its own circuit. --dns also offers a DNS resolver on loopback that answers
through the network.

If tor stops, up exits with an error and the proxy port closes; applications
using it fail instead of connecting some other way.

orama nodes [flags]

List all nodes owned by your wallet. Queries the network API
with your stored credentials, falling back to nodes.conf.

Requires: orama auth login (for API-based resolution)

orama remove [flags]

Take one node out of every store the network keeps, then wipe it.

Before anything changes, remove prints what the removal costs every raft cluster
the node is a voter in (the platform cluster and each namespace it serves) and
refuses if any of them would lose quorum. It also refuses:

  a node in the validator set       erasing it destroys the validator's consensus key
                                    and jails the validator; move the key first, or
                                    pass --drop-validator
  a node with the global layer      it may be registered on the chain with a bond; say
                                    what happens to that: --chain-node-id <id> retires
                                    it, --no-chain leaves it
  a node that holds storage deals   the chain refuses to retire a node whose deals
                                    still reserve bytes

With --chain-node-id the node is retired on the chain first (MsgRetireNode, signed
by your RootWallet, sent through a surviving node's chain over SSH): its service keys
are revoked and its bonds start to unbond. If the chain or the RootWallet refuses,
nothing has been removed. Then the node leaves the raft configuration, an eviction
tombstone keeps anything from re-adding it, its mesh address, nameserver slot,
namespace memberships, port blocks and TURN and SFU allocations are released, its DNS
records are purged, and the machine is wiped.

Use --offline when the machine is already gone: the removal is done from the
survivors and nothing is attempted on the target. It cannot be asked whether it
was registered on the chain, so its registration is left alone and the plan says
so; --chain-node-id retires it through a surviving node. Every step is keyed on the node and
safe to repeat, so a removal that failed part way is finished by running it again.

--dry-run prints the quorum arithmetic and every step, changing nothing. This is
DESTRUCTIVE: it asks you to type 'yes' unless --yes is given.

Examples:
  orama remove --node 203.0.113.9 --dry-run
  orama remove --node 203.0.113.9
  orama remove --node 203.0.113.9 --chain-node-id node-9
  orama remove --node 203.0.113.9 --offline

orama ssh <ip-or-hostname> [-- command] [flags]

SSH into a node by IP address or hostname.
Resolves the SSH key from rootwallet automatically.

The node's host key must already be pinned in ~/.orama/known_hosts, where
'orama node setup' writes it. A host with no pinned key is refused, never
trusted on first use, and a key that differs from the pinned one is refused.

Pass a command after the IP to run it non-interactively:
  orama ssh 203.0.113.4 'sudo systemctl status orama-node'

orama upgrade [flags]

Fetch the newest release of your network's channel, show what each node runs and
what it will go through, and after you confirm, upgrade the nodes one at a time.

The release comes from the release repository and channel the network publishes
(orama network list). It is verified here against the release root built into this
CLI before anything is sent: the signed metadata, then the archive's length and
hashes. Every node verifies it again against the release root it adopted, and
refuses a release that does not match, before it replaces a file.

The plan lists each node with the release it runs now (from the cluster's
telemetry, as 'orama status' shows it), the release it will run, and its place in
the rollout: followers first, nameservers spread so the zone keeps answering, the
raft leader last. A node that already runs the release is left alone
(--reinstall puts it in place again); a node that runs a newer one is never
downgraded.

The release is staged on every node first, which restarts nothing. Then each node
in turn is upgraded and restarted, and the next one starts only when that node is
healthy and carrying its share of the cluster again: never two RQLite voters at once.
A node that has the global layer also refreshes it right after its own upgrade:
the global binaries are replaced, and the services that run them are restarted.
The chain binary (oramad) is staged for cosmovisor only when the release carries
another one and the chain has a governed upgrade scheduled; otherwise the running
oramad is kept and the output says so.

--node upgrades one node. --dry-run prints the plan and stops.

Examples:
  orama upgrade --dry-run          # What would change
  orama upgrade                    # Show the plan, ask, then roll
  orama upgrade --yes              # Roll without asking
  orama upgrade --node 203.0.113.7

orama version