rookery serve
One API over all your hosts, with an inbox of their messages and a key-value store, for scripts, user interfaces and other machines' Rookery.
rookery serve offers one API over every saved host. It reaches each host the way the terminal UI does and passes the host's own operations through, so a program can use all hosts without SSH of its own. Every operation is in the API reference.
rookery serveIt prints where it listens and how many hosts it knows. Only one runs per user. To use its hosts from another machine's Rookery, see A Rookery server. To test an application against the API without machines, see Testing against a simulated server.
What it adds
| Operations | For |
|---|---|
hosts.* | The saved hosts and their profiles, and whether each is behind. Each says its type, the type it was seen to be, and whether a key rotation has yet to reach it. hosts.save takes a host that is not a workstation with only type and access. hosts.actions lists what can be done to a host and hosts.act runs one of those actions |
installation.* | The actions of the installation itself, such as rollout, which applies the hosts that are behind one after another |
secrets.*, registries.*, settings.* | What the server keeps beside the hosts. A secret's value goes in and never comes back out |
plugins.* | The server's plugins. One is installed from its npm registry, from an https:// address, or from a .tgz that is sent, and one of its own is removed. plugins.check asks the registries for newer versions and plugins.update installs them. setup.catalogue lists the new features straight away |
provisioners.* | The provisioners of the plugins with their pages and actions. A page lists what Rookery made with the provisioner, by kind. An action of a provisioner has its own role (Provisioners) |
resources.* | What provisioners made for Rookery, such as a host's machine or a deployment. Creating, changing and removing one are jobs of the subject resource:ID and need the role admin. Its log needs operate, and its actions have their own roles (Resources) |
| Every rookeryd operation | With a host: "host": "NAME" on the portal, /v1/hosts/NAME/controller/… over HTTP. Only the controller's own secrets action is refused; the server's secrets action of the host sends the server's own |
jobs.* | Jobs, one for each run of an action that runs here or follows one of a host's controller, with their output. Each says its subject and its action. A roll-out's job has a report, host by host |
inbox.* | Messages the hosts published on their channels and kept, taken in while rookery serve runs; each can be marked done |
kv.* | A key-value store with revisions, for user interfaces to keep state in |
events.follow | One stream of channel messages, jobs, key-value changes and changes to hosts and resources, at /v1/events |
All of it is also on the portal, the one WebSocket at /v1/portal for calls and streams together.
Actions
What Rookery does to a host or to the installation is an action. GET /v1/hosts/NAME/actions lists a host's, and GET /v1/installation/actions lists those of the installation. A host's controller has actions of its own, which are among the host's here. Its own list, actions.list, is at /v1/hosts/NAME/controller/actions. A form can be built from an action's description. It has the arguments with their defaults and choices, a question to confirm, the least role, and whether it can run now.
| Action | Of | Runs | Answers |
|---|---|---|---|
An action of the host's controller, such as status | The host | On the host, as a session | 202 with the session and a job that copies its output. One that needs a terminal answers 200 with the session alone, to attach to |
apply | The host | Here, as a job | 202 with the job |
install-controller | The host | Here, as a job | 202 with the job. It installs rookeryd and box alone on an ssh or managed host |
seed | The host | Here, at once | 200 with the seed's user_data as the result |
secrets | The host | On the host, with the server's secrets | 202 with the session and its job |
rename | The host | Here, as a job | 202 with the job. It gives the host the name in its name argument, with what the server keeps of it (Renaming a host) |
upgrade-server | A node with a Rookery server's container | On the node, as a session | 202 with the session and its job. It runs the server from the image of version, this server's own unless given (The Rookery server on a node) |
rollout | The installation | Here, as a job | 202 with the job; its report says how each host went |
An action that the host's type rules out is listed with available false, and its why says which action changes the type. Run anyway, it is refused with 501 not_available.
To run one, POST to its name with its arguments:
curl --unix-socket "$XDG_RUNTIME_DIR/rookery/serve.sock" -X POST \
-d '{"arguments": {"update": "yes"}, "token": "nightly-2026-11-13"}' \
http://rookery/v1/installation/actions/rolloutThe token is optional. The same token again for the same subject and action answers with the job the first request started, and nothing runs a second time. That lets a caller that lost the answer ask again. While an action changes a host, a second one that changes it is refused with 409 until the first has ended, and so is a second roll-out. A job is followed with jobs.get, jobs.output and the jobs.follow stream, and the events stream says when it starts and ends.
The inbox, jobs and key-value store are kept in Rookery's store for retention_days (90 by default), and are also readable without the server:
rookery inbox list studio --topic ask/ # what is open; --all includes what is done
rookery inbox done studio 12 # marks message 12 of studio done
rookery kv set ui layout '{"columns": 2}'
rookery kv list uiThe store
The store is where Rookery keeps the host profiles, with their generated passwords and the records of the machines it created. It also keeps the registries, secrets and settings. Rookery's own SSH key, the server's token and setup key and the list of your own plugins are there too, with the inbox, jobs and key-value store. It is rookery.db, a SQLite file in Rookery's data directory, unless the store setting or ROOKERY_STORE names another file or a PostgreSQL database. The store says how to choose it, encrypt it, move it to another database and restore a server from it.
rookery serve serves the hosts of its own installation.
| Command | Does |
|---|---|
rookery host export HOST | Prints a host's profile as JSON |
rookery host import HOST FILE | Saves the profile in FILE as the host's, - for standard input |
rookery host credentials HOST | Prints the passwords Rookery generated for the host's accounts. hosts.credentials gives them to an admin of the server |
rookery server store status says where the store is and whether its values are encrypted, and rookery server store encrypt seals them with a key file (Encrypt it).
Where it listens
Always: $XDG_RUNTIME_DIR/rookery/serve.sock, readable by your user only. Requests there do not need the token.
curl --unix-socket "$XDG_RUNTIME_DIR/rookery/serve.sock" http://rookery/v1/hostsWho gets in
A caller over TCP shows the server's token or an OAuth 2.0 access token, and acts with one of three roles. Each role includes the ones before it:
| Role | May |
|---|---|
view | Read what the hosts and the server report, such as sessions with their output, logs, jobs and the inbox |
operate | Work on the hosts with actions, commands, terminals and files. Units, power and the key-value store are included |
admin | Change profiles, secrets, registries, settings and plugins, apply a profile to a host, and create or delete the machine of a host |
Each action has a role of its own, which is checked when it runs. The actions of a host's controller need operate, Rookery's own actions admin.
The server's token is admin. The socket doesn't ask for a token and is admin too. The API reference lists the role of each operation, and access tells a caller its own.
Access tokens from an OAuth 2.0 issuer
rookery serve can act as an OAuth 2.0 resource server. It then takes access tokens signed by an issuer you already run, such as Keycloak or Zitadel. Rookery doesn't keep users or sessions. The issuer decides who gets which role.
rookery config set oauth_issuer https://id.example.com/realms/main
rookery config set oauth_audience rookery| Setting | Meaning |
|---|---|
oauth_issuer | The issuer's address, as in the tokens' iss. Its keys are found through its metadata |
oauth_audience | The aud a token needs. Without it the audience is not checked |
oauth_claim | The claim with the role in it, scope by default. Dots go into objects, as in realm_access.roles |
oauth_jwks | The address of the issuer's keys, when its metadata is not at the usual place |
serve_token | off: only access tokens get in, the server's own token does not |
A token is a JWT signed with one of the issuer's keys (RSA, ECDSA or Ed25519). It needs iss and exp, and the role in the claim: rookery:view, rookery:operate or rookery:admin. In a claim other than scope the bare view, operate and admin count too. The highest role named is the caller's.
The roles can be written in the claim three ways:
| Claim's value | Example | Roles read |
|---|---|---|
| Text | "openid rookery:operate" | The words, split at spaces and commas |
| List | ["rookery:view", "admin"] | Each entry |
| Object | {"admin": {…}, "billing": {…}} | Each key. Zitadel writes project roles this way, in urn:zitadel:iam:org:project:roles |
curl -H "Authorization: Bearer $ACCESS_TOKEN" https://rookery.example.ts.net/v1/access
# {"role":"operate","setup":true,"subject":"ada"}An access token is used like the server's token. It works as a bearer and as the WebSocket protocol. Rookery takes it with --token-file or --token-stdin, as ROOKERY_TOKEN, or kept by rookery login, and the screens when they ask for it.
The server says which issuer it trusts at /.well-known/oauth-protected-resource, without a token.
Rookery has no login of its own. Get an access token from the issuer by your own means, and give it to Rookery as ROOKERY_TOKEN. A wrapper script does that, and the token stays out of argv:
ROOKERY_TOKEN=$(curl -s -d grant_type=client_credentials -d client_id=rookery-ci \
--data-urlencode client_secret@/etc/rookery-ci.secret \
https://id.example.com/token | jq -r .access_token)
export ROOKERY_TOKEN
exec rookery "$@"Each of these settings can also come from the environment, as ROOKERY_ and the name in capitals. That suits a container, or Rookery running inside another program:
docker run -d -e ROOKERY_OAUTH_ISSUER=https://id.example.com/realms/main \
-e ROOKERY_OAUTH_AUDIENCE=rookery -e ROOKERY_SERVE_TOKEN=off … ghcr.io/aiviarium/rookeryClosing set-up
By default an admin can set the server up over the network. To keep that on the server itself:
rookery config set serve_setup offA caller over TCP is then operate at most, and the socket stays admin. Some things are refused from a caller of any role:
- The settings that say who gets in and where the server's files are.
settings.settakes onlydefault_hostandretention_days. - A profile's
access.link, which is a command the server runs, andaccess.authssh, the SSH configuration of the server's own account. - A path on the server as what
plugins.addinstalls. It takes a package name or anhttps://address, andplugins.uploadtakes a.tgz. - Building a USB installer, which needs the drive.
In a container
The ghcr.io/aiviarium/rookery image runs rookery serve --listen 0.0.0.0:7777 --expose by default, as user rookery (uid 1000):
docker run -d --name rookery -p 127.0.0.1:7777:7777 \
-v rookery-config:/config -v rookery-data:/data \
-v ~/.ssh:/home/rookery/.ssh:ro \
ghcr.io/aiviarium/rookery
docker exec rookery cat /data/rookery/serve.token| Path | Holds |
|---|---|
/config/rookery/ | config.json with the settings of this machine, the key file of an encrypted store, and the folder of the server's own plugins |
/data/rookery/ | The store, unless ROOKERY_STORE names a PostgreSQL database. Beside it serve.token and the server's SSH key, written from the store, the output of jobs, and builds |
/home/rookery/.ssh | Further SSH keys and configuration for reaching hosts |
The image contains ansible-core, the OpenSSH client and Python, so it can also apply configurations, and npm for installing plugins. See A Rookery server for using it from Rookery on another machine, and The store for keeping its state in PostgreSQL.
The API documents
rookery server api operations # every operation, for the portal and HTTP
rookery server api openapi # OpenAPI 3 for the HTTP routes
rookery server api asyncapi # AsyncAPI 3 for the streamsThe API reference is generated from them.
Last updated on