orama namespace

orama namespace

List, delete, and repair namespaces on the Orama network.

orama namespace backup [flags]

Ask the namespace gateway for a backup: its RQLite snapshot, the CIDs it
has pinned, and its secrets, decrypted by the cluster and sealed with the rest
to the public key you give. The cluster never holds the private key and cannot
open what it wrote. Keep the private key off the cluster.

--out writes the sealed file. --deal-dir also seals it into one slot-N file per
replica of a private storage deal (under your orama-storage-v1 key and repair
seed) and prints the 'orama storage create' and 'orama storage put' commands
that open the deal and upload the slots. Restore it from the deal with
'orama namespace restore --from-deal'. The backup is taken when you run the
command; the cluster does not take or store backups by itself.

It goes to the namespace's own gateway (the host 'orama auth login --namespace'
stored). With ORAMA_TOKEN, set ORAMA_API_URL to that host
(https://ns-<name>.<domain>): the environment's gateway does not serve backup.

orama namespace backup-open [flags]

orama namespace backup-seal [flags]

Encrypt a file to the owner's backup public key.

The cluster holds only that public key. It cannot decrypt the file.
This seals any file. A namespace's own backup is 'orama namespace backup', and
putting one back is 'orama namespace restore'.

orama namespace create <name>

Create a namespace. The wallet you are signed in as becomes its owner.

Creating a namespace used to happen by itself: signing in to a name that did
not exist created it. So a typo made a namespace, and one belonged to whoever
happened to sign in first.

  orama namespace create myapp
  orama auth login --namespace myapp

orama namespace delete [flags]

orama namespace disable <feature> [flags]

Disable a feature for a namespace. Supported features: webrtc, webrtc-stealth

orama namespace enable <feature> [flags]

Enable a feature for a namespace. Supported features: webrtc, webrtc-stealth

orama namespace keys

Create, list, and revoke scoped API keys. Profiles: invoke-only | app-runtime | admin.

orama namespace keys create [flags]

orama namespace keys list [flags]

orama namespace keys revoke [flags]

orama namespace keys revoke-legacy [flags]

orama namespace keys rotate [flags]

Mint a new key with the same grants and label, and shorten the original's life
to the overlap.

Rotating by minting a new key and revoking the old one in the same breath is an
outage: whatever is deployed with the old key stops the moment the new one
exists. The overlap is the window in which to deploy the successor — both keys
work, and the original then expires on its own.

orama namespace list

orama namespace repair <namespace>

Repair an under-provisioned namespace cluster. Run it on a node. It talks to that node's gateway on the node's WireGuard address; localhost is where public traffic arrives, so a repair sent there is refused.

orama namespace restore [flags]

Open a backup on this machine with your private key, seal its secrets to
the destination gateway's restore key (--dest-key, from 'orama namespace
restore-key'), and send it to the namespace gateway you are signed in to.

The gateway replaces the namespace's entire RQLite database with the backup,
writes the secrets under its own cluster's encryption root, and pins every CID
in the backup. The namespace must already exist on the destination, and
--namespace must name the namespace the backup was taken of. A wrong key, a
corrupt file or a different namespace stops before anything is sent.

The sealed backup is the file at --in, or the private storage deal that holds
it (--from-deal, with --rpc and your storage key and repair seed files): the
first slot a provider serves with the on-chain root is fetched and opened.
Give one of the two.

The gateway also refuses, before writing anything, a restore that would put
the namespace over its storage quota on the destination, and it keeps the
destination's quota rather than the one in the backup. It runs one backup or
restore at a time and answers 429 while one is running.

The live keys, grants and sessions (in the cluster's registry) are not
restored: a restore neither brings back a key that was revoked nor removes one
minted since. The backup's database still carries stale copies of those rows,
which nothing reads. Before loading, the gateway checks the database image and
refuses (400, nothing written) one that is damaged or carries triggers, views
over platform tables or stored-object records for content only other namespaces
hold; it removes plaintext API keys and other namespaces' records an older backup
may carry, and checks again, after the load.

With ORAMA_TOKEN, set ORAMA_API_URL to the namespace's gateway
(https://ns-<name>.<domain>): the environment's gateway does not serve restore.

orama namespace restore-key

Print the X25519 public key a restore's secrets are sealed to. It is
derived from the destination cluster's encryption root and the namespace, so
it is different for every namespace and changes when that root is rotated.
Pass it to 'orama namespace restore --dest-key'.

orama namespace rqlite

Export and import the namespace's internal RQLite database: your own tables and the
namespace's functions, function secrets, stored-object records, quotas and push and
WebRTC settings. Keys, grants and deployments are in the cluster registry, not in it.

Both go to the namespace's own gateway (the host 'orama auth login --namespace' stored).
With ORAMA_TOKEN, set ORAMA_API_URL to that host (https://ns-<name>.<domain>): the
environment's gateway does not serve them.

orama namespace rqlite export [flags]

Downloads a consistent SQLite snapshot of the namespace's internal RQLite database.

orama namespace rqlite import [flags]

Replaces the namespace's entire RQLite database with the contents of the provided SQLite file.

WARNING: This is a destructive operation. All existing data in the namespace's RQLite
(your tables, functions, function secrets, stored-object records, quotas and push and
WebRTC settings) will be replaced with the imported file. The file must be a SQLite
database, as 'export' writes; at most 256 MiB. Live keys and grants (in the cluster
registry) are not replaced, and stale copies in the file are ignored. The namespace's
storage quota stays as it was. The gateway checks the file before loading it and
refuses (400, nothing written) one that is damaged or carries triggers, views over
platform tables or stored-object records for content only other namespaces hold;
it removes plaintext API keys and other namespaces' records an older file may carry,
and checks again, after the load. One backup, restore, export or
import runs at a time on a gateway.

orama namespace session-policy [flags]

With no flags, show the namespace's session policy. With flags, set them; a flag
left out keeps its value.

  --sign-in members   only wallets holding a grant sign in (the default)
  --sign-in open      a wallet holding none may sign in too, as an end user of
                      the application. It gets a session and no API key, is
                      never granted anything, and reaches only what a grantless
                      wallet reaches. Closing it again ends those sessions at
                      their next refresh. A namespace nobody owns stays closed.

  --device-policy     optional | required | approval: what an end user's
                      sign-in must bind. Requiring devices revokes the sign-in
                      keys end users already hold.

Changing either needs write access to the namespace.

  orama namespace session-policy --namespace myapp --sign-in open

orama namespace webrtc-status [flags]