Skip to Content

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 serve

It 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

OperationsFor
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 operationWith 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.followOne 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.

ActionOfRunsAnswers
An action of the host's controller, such as statusThe hostOn the host, as a session202 with the session and a job that copies its output. One that needs a terminal answers 200 with the session alone, to attach to
applyThe hostHere, as a job202 with the job
install-controllerThe hostHere, as a job202 with the job. It installs rookeryd and box alone on an ssh or managed host
seedThe hostHere, at once200 with the seed's user_data as the result
secretsThe hostOn the host, with the server's secrets202 with the session and its job
renameThe hostHere, as a job202 with the job. It gives the host the name in its name argument, with what the server keeps of it (Renaming a host)
upgrade-serverA node with a Rookery server's containerOn the node, as a session202 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)
rolloutThe installationHere, as a job202 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/rollout

The 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 ui

The 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.

CommandDoes
rookery host export HOSTPrints a host's profile as JSON
rookery host import HOST FILESaves the profile in FILE as the host's, - for standard input
rookery host credentials HOSTPrints 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/hosts

Who 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:

RoleMay
viewRead what the hosts and the server report, such as sessions with their output, logs, jobs and the inbox
operateWork on the hosts with actions, commands, terminals and files. Units, power and the key-value store are included
adminChange 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.

On the server
rookery config set oauth_issuer https://id.example.com/realms/main
rookery config set oauth_audience rookery
SettingMeaning
oauth_issuerThe issuer's address, as in the tokens' iss. Its keys are found through its metadata
oauth_audienceThe aud a token needs. Without it the audience is not checked
oauth_claimThe claim with the role in it, scope by default. Dots go into objects, as in realm_access.roles
oauth_jwksThe address of the issuer's keys, when its metadata is not at the usual place
serve_tokenoff: 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 valueExampleRoles 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/rookery

Closing set-up

By default an admin can set the server up over the network. To keep that on the server itself:

On the server
rookery config set serve_setup off

A 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.set takes only default_host and retention_days.
  • A profile's access.link, which is a command the server runs, and access.auth ssh, the SSH configuration of the server's own account.
  • A path on the server as what plugins.add installs. It takes a package name or an https:// address, and plugins.upload takes 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
PathHolds
/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/.sshFurther 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 streams

The API reference is generated from them.

Edit on GitHub

Last updated on

On this page