First run¶
A fresh node has no tenants and no services. In this step you act as the operator: you learn what the two node secrets do, then create a tenant and an API key that a developer (also you, for now) uses to deploy code.
The two node secrets¶
- Root token (
RT_ROOT_TOKEN) - The operator's credential for the control API, sent as
Authorization: Bearer <token>(the root token is never accepted inx-rt-key). It can call every route, including the operator-only ones under/v1/nodeand/v1/tenants. Any string works; use a long random one (openssl rand -hex 32). - Master key (
RT_MASTER_KEY) - 32 random bytes written as 64 hex characters. It seals tenant secrets with AES-256-GCM and derives the other node keys (the pepper for API-key hashes, the integrity key of the compiled-code cache). It never leaves the node.
Both can come from a file instead: RT_ROOT_TOKEN_FILE and RT_MASTER_KEY_FILE (set the variable or the _FILE
variant, not both). If no master key is configured at all, rt generates <data_dir>/master.key (mode 0600) on first
start.
Back up the master key, separately from the data
Without the master key, sealed secrets cannot be opened and existing API keys stop verifying. Store it apart from the data volume backups. To change it later, follow the rotation procedure in Production deployment; never just swap the value.
Configure the CLI as operator¶
A 21ci context names a node: its control URL, invoke URL and token.
set -a; . ./.env; set +a # loads RT_ROOT_TOKEN from the compose .env (on a `make dev` node it is dev-root-token)
21ci config set-context local --api http://127.0.0.1:8081 --invoke http://127.0.0.1:8080 --token "$RT_ROOT_TOKEN"
21ci doctor
CHECK STATUS DETAIL
config ok context local; /home/me/.config/21ci/config.toml
credentials ok root token (operator)
control api ok http://127.0.0.1:8081 answers in 3 ms (API 1.0.0)
auth ok operator: node routes allowed
version ok client 0.1.0, node 0.1.0
node mode ok normal
invoke listener ok http://127.0.0.1:8080 answers in 2 ms (HTTP 404)
21ci doctor checks the context, the token, both listeners and the client/node versions in one go. 21ci node status
shows the node itself:
$ 21ci node status
Version: 0.1.0
Mode: normal
Default profile: balanced
V8 sandbox: false
Processors: 10
Kinds: deno=8 wasm=2 build=1
In flight: 0
Memory: {"budget_bytes":268435456,"pressure":"Normal"}
Create a tenant¶
A tenant owns services and keys and gets a plan that sets its quotas and limit maxima. The built-in plan free
always exists; operators add more under [plans.<name>] in rt.toml
(Tenants, plans and keys).
The free plan allows 10 services, 50 requests per second, 100,000 invocations per day, 100 MB of storage, and per-task
limits up to 30 s wall time, 1 s CPU and 128 MB of memory. It does not allow cron schedules.
Create an API key for the tenant¶
Tenant keys look like rtk_<key_id>_<secret>. The full secret is returned once; the node stores only a hash.
$ 21ci key create --tenant ten_01M3XM135SCP9EP41ZZXAQ5CCZ --name laptop
ID: key_01M3XM1AG5HN6WY9S6JQ550JQV
Name: laptop
Scopes: services:read,services:write,deploy,invoke,logs:read,env:write,secrets:write,queue:write
Services: all
Expires: never
Created: 2026-10-02T06:15:14Z
Secret: rtk_01M3XM1AG5HN6WY9S6JQ550JQV_dtok…
The secret is shown only once: store it now.
curl -sS -X POST "$RT_API/v1/tenants/ten_01M3XM135SCP9EP41ZZXAQ5CCZ/keys" \
-H "Authorization: Bearer $RT_ROOT_TOKEN" -H 'Content-Type: application/json' \
-d '{"name":"laptop","scopes":["services:read","services:write","deploy","invoke","logs:read","env:write","secrets:write","queue:write"]}' \
| jq -r .secret
Without --scopes, 21ci grants every scope except data:admin; with the API, scopes is required. The scope table, how to
restrict a key to some projects and environments, expiry, rotation and acting for a tenant with the root token (--as-tenant) are in
Get access.
Switch to the tenant¶
Services always belong to a tenant, and day-to-day work is safer with a tenant key than with the root token: a key cannot touch other tenants or the node. Save the key in a second context and make it current:
21ci config set-context demo --api http://127.0.0.1:8081 --invoke http://127.0.0.1:8080 --token rtk_01M3XM1AG5HN6WY9S6JQ550JQV_dtok…
21ci config use-context demo
21ci whoami # tenant, key, scopes and plan behind the current token
An exported RT_ROOT_TOKEN beats the context
21ci takes the token from RT_KEY, then RT_ROOT_TOKEN, then the context. If the set -a; . ./.env step above left
RT_ROOT_TOKEN in your shell, 21ci whoami still reports Principal: operator after use-context demo. Run
unset RT_ROOT_TOKEN first.
Or skip contexts and export the variables, which always win over a context and are what scripts, CI and the curl
examples in these docs use:
export RT_API=http://127.0.0.1:8081 # control listener
export RT_INVOKE=http://127.0.0.1:8080 # public invoke listener
export RT_KEY=rtk_01M3XM1AG5HN6WY9S6JQ550JQV_dtok…
Next steps¶
You have a tenant and a key. Continue with Your first service.