Agent index (llms.txt) — fetch this first, then the page it names.
Namespaces
A namespace is the unit you build in. It is your own small cluster inside the Orama cluster: its own database, its own cache and its own gateway, on three nodes, with its own keys, members and audit trail. Everything else in these docs (deployments, databases, functions, storage, pub/sub) happens inside one.
In most platforms a tenant is a column in a shared table. In Orama a tenant is a cluster, so there is no cross-tenant query to get wrong.
What creating one does
orama namespace create myapp
- +Checks the name, and that the wallet you are signed in as may create namespaces on this cluster.
- +Picks three nodes, weighted by free capacity, treating machines that share a public IP as a single failure domain.
- +Reserves a block of five ports on each node, from a range that allows up to 20 namespaces per node.
- +Starts the namespace's RQLite, Olric and gateway units, in that order, on each of the three.
- +Publishes DNS for
ns-myapp.<base-domain>and a wildcard under it. - +Records you as the namespace's owner.
You own what you create. Ownership is the only thing that writes an owner grant: signing in to a name that does not exist answers 404, and signing in to one with no owner is refused (NAMESPACE_UNOWNED).
Names
2 to 40 characters of lowercase letters, digits and hyphens, not starting or ending with a hyphen. A name becomes a DNS label (ns-<name>.<base-domain>), a systemd instance name and a directory, so it is held to what all three accept. These are reserved by the platform and refused: default, index, nameserver, system, orama, admin, internal, api, www, mail, cdn, docs, status, push, turn, ns1, ns2, ns3, ns4.
Who may create one
A new cluster lets only its operators create namespaces. An operator can allow an allowlist of wallets or any signed-in wallet, and can set how many a wallet may own (default 10, range 1 to 10,000). See Cluster administration. Creating a namespace on a cluster also needs an EVM wallet (a 0x address). The cap holds for a transfer too: transferring a namespace to a wallet that already owns that many is refused 403 TRANSFER_REFUSED, a generic answer that names neither the wallet nor the limit, and the owner keeps the namespace. A cap lowered afterwards does not take namespaces from a wallet that owns more; it only stops that wallet receiving or creating another.
How many nodes
| Cluster size | Namespace size |
|---|---|
| 1 node | One node, for evaluation. Not highly available |
| 2 nodes | Refused. An even-sized Raft group cannot survive losing either member |
| 3 or more nodes | Three nodes, always |
If the cluster has three or more nodes but fewer than three with a free namespace slot, creation is refused with 503 NAMESPACE_CAPACITY and nothing is created. See One-VPS evaluation.
Using a namespace
Your namespace has two addresses:
| Address | Serves |
|---|---|
https://ns-myapp.<base-domain> | The namespace's own gateway: database, cache, pub/sub, storage, functions, WebRTC |
https://<base-domain> | The cluster gateway: sign-in, namespace creation, the lobby, operator functions |
The SDK's baseURL is the first. CLI commands that act on a namespace use the stored session for it; --namespace <name> picks one.
orama namespace list # namespaces owned by the signed-in wallet orama auth login --namespace myapp orama auth list # every stored credential orama auth switch # change the active one
What is inside
| Part | Where to read |
|---|---|
| Members, roles, grants, API keys, the audit trail | Access control and keys |
| Who may sign in, and device policy | Sign-in and sessions |
| Deployments and domains | Deployments, Domains |
| SQL, cache, files, messages | Databases, Cache, Storage, Pub/sub |
| Functions and their secrets | Functions |
| Voice and video | WebRTC |
| Push credentials | Push notifications |
Platform state is kept apart from your data
Your namespace's own database contains none of the platform's identity tables (keys, grants, sessions, signing keys, audit events). They live in the cluster registry, which your database cannot read or rewrite. A single placement list decides which database each table belongs to, and a test fails if a new table is left unplaced. This is why you can export and import your namespace database whole without touching your keys or members.
Enabling optional features
orama namespace enable webrtc # voice and video (needs the namespace on three nodes) orama namespace enable webrtc-stealth # TURN on port 443, see Stealth TURN orama namespace disable webrtc orama namespace webrtc-status
See WebRTC and Stealth TURN.
Backing up, moving, deleting
orama namespace backup --key <public key hex> --out myapp.orbk # sealed to your key orama namespace rqlite export # the database as a SQLite file orama namespace delete # the signed-in namespace and everything in it
See Backups and restore. Only the owner deletes a namespace. If the owner's wallet is lost, an operator removes it with orama cluster namespace remove.
Repair
A namespace's units start only on the cluster the registry names as its current one. A start request names its cluster and is refused 409 when it is not the namespace's current cluster, and a namespace deleted while it was provisioning gets no units, so a late provisioner cannot revive a namespace that was deleted and created again.
A namespace with fewer healthy members than it should have is under-provisioned. Node replacement normally fixes this on its own within a minute (the tenant reconciler rewrites configurations and prunes departed members). To force it, run on a node: sudo orama namespace repair myapp. See Replace a node.