Skip to Content

A Rookery server

Run a Rookery server on one machine and use its hosts from Rookery on other machines.

A server machine keeps the hosts with their profiles and secrets, and runs rookery serve. Rookery on another machine, such as your laptop, then uses that server: the screens, rookery ls, rookery run and every other command call the server's API through its portal. On macOS and Windows Rookery is only that: a client of a server.

 your laptop                  the server                       hosts
┌─────────────┐  HTTPS/HTTP  ┌───────────────────────────┐ SSH ┌─────────┐
│ rookery       │ ───────────▶ │ rookery serve               │ ──▶ │ studio  │
│ --server …  │   + token    │ profiles, secrets, builds │ ──▶ │ cloud-1 │
└─────────────┘              └───────────────────────────┘     └─────────┘

Run the server

The server needs SSH access to the hosts. The container image is the shortest way:

On the server
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 rookery server setup-key

Without the image, run rookery serve --listen 0.0.0.0:7777 --expose where Rookery is installed. The last command makes a setup key, which hands the server's token to its first user.

The server keeps its state in one store, a SQLite file by default. The store says how to keep it in PostgreSQL, encrypt it and restore the server on another machine from it.

Put TLS in front

rookery serve speaks plain HTTP, and the token gives full control of every host. Serve it behind a TLS proxy, such as Tailscale Serve or Caddy, and use the https:// address. Without one, keep the port on loopback or a private network such as your tailnet.

With Tailscale on the server:

On the server
sudo tailscale serve --bg --https=443 http://127.0.0.1:7777

Connect to it

rookery login keeps the server and its token, and every command after it uses that server:

rookery login https://rookery.example.ts.net    # asks for a setup key
rookery ls
rookery run studio status
rookery logout                                # back to the rookery of this machine

With the token in a file instead, rookery login https://rookery.example.ts.net --token-file token keeps it. For one command alone, give the server on its command line. That leaves the kept one alone:

rookery --server https://rookery.example.ts.net --token-file token ls

ROOKERY_SERVER and ROOKERY_TOKEN in the environment take precedence over what rookery login kept. A token never goes on the command line, where other users of the machine could read it.

With a setup key

A setup key lets the first user collect the token without reading serve.token on the server. Whoever installs the server, such as a coding agent, hands on the key and never sees the token. Make one where the server keeps its data:

On the server
docker exec rookery rookery server setup-key       # or: rookery server setup-key

It prints the key. On your own machine, give it to rookery login when it asks, or on standard input with --setup-key-stdin:

rookery login https://rookery.example.ts.net

Rookery checks the key, collects the token and keeps the server and the token. The key lasts 24 hours, and ends once rookery login has saved the token. Until then it's as good as the token, so keep it to yourself. A new key replaces the old one, and rookery server setup-key --revoke ends it. A server with serve_token off has no token to hand out, so it doesn't make a key.

AddressReaches
https://HOST[:PORT]A server behind a TLS proxy
http://HOST:PORTA server's port directly
unix:/path/to/serve.sockA rookery serve on this machine, without a token

On other systems

Rookery on macOS and Windows is the client of a server: the screens and the commands, which all call a server. Install it on Windows in PowerShell:

irm https://raw.githubusercontent.com/aiviarium/rookery/main/install.ps1 | iex

On macOS:

curl -fsSL https://raw.githubusercontent.com/aiviarium/rookery/main/install.sh | sh

Each script downloads the latest release for this machine, checks it against its SHA-256 and installs it, to %LOCALAPPDATA%\Programs\rookery on Windows and to ~/.local/bin on macOS. ROOKERY_INSTALL_DIR and ROOKERY_VERSION work as on Linux. To download it by hand, take the archive for your system and its .sha256 file from the latest release.

Then connect it with a setup key, and open the screens. On Windows, use Windows Terminal or the console of Windows 10 or later.

rookery login https://rookery.example.ts.net
rookery ui

Rookery keeps the server and the token in the folder of Rookery's settings. When none is kept, the screens open with a form for a server's address and token.

VariableEffect
ROOKERY_SERVERThe server, for this run
ROOKERY_TOKENThe token, so it isn't asked for
ROOKERY_FILEThe plugin package the screens send, where there is no file dialog

Rookery talks to a server over https only with a certificate that the system or the Mozilla roots trust. It opens only http and https links, in the system's browser. o on the host list signs out.

A password the server makes up is shown once. The server keeps a copy in its store, and rookery host credentials HOST shows it again to an admin of the server.

What works with the server's own machine is offered there only. That is the USB installer, which writes a drive of that machine, and the settings that aren't open to the network. Elsewhere the screens list them as unavailable, with the reason.

What works from another machine

Every command calls the server. Each works from another machine as it does on the server. These are the exceptions: they need the server's own machine, and say so elsewhere.

Needs the server's machineWhy
Writing the USB installer to a driveThe drive is a device of that machine
rookery ssh HOSTIt uses that machine's SSH configuration and keys
rookery registry publish and rookery registry push-imageThey upload files of that machine
rookery server … and rookery serveThey are the server itself
The settings that aren't open to the networkThe server keeps them to its own users

Setting the server up from here

With the role admin on the server, which its token has, Rookery sets the server up from anywhere. What you change is saved on the server:

  • A host's set-up tabs, rookery host create, rookery host set and rookery host import save the profile there.
  • A password the server generates is kept there. rookery host credentials HOST asks the server for it.
  • rookery apply HOST and Apply this configuration run as a job on the server. Rookery follows its output as it comes (Jobs).
  • rookery host seed HOST has the server render the cloud-init seed, and writes it here.
  • rookery host create HOST --provisioner NAME, rookery host start and rookery host stop use the server's provisioners and secrets (Provisioners).
  • rookery resource uses the server's resources. A deployment's specification is sent to the server and kept there, and it gets the server's secrets (Deployments).
  • A secret's value is sent to the server and kept only there.
  • The tailnet_ settings and the secret tailnet_api_key are the server's, which creates the keys its hosts join with and looks after their devices. Settings and rookery config set change them there.
  • A plugin is installed on the server, and its features show on the Features tab of the server's hosts. A .tgz or folder of yours is sent there first.
  • The server logs in to hosts with the keys of its own key ring, by default its key rookery. rookery key acts on the server's ring, and its private halves stay there. rookery key trust HOST and rookery host verify HOST --accept make first contact and accept a changed host key from the server.
  • rookery key rotate replaces a key on the hosts that take it, as a job of the server (Rekeying).

With a lesser role the set-up tabs say This host is set up on the Rookery server at URL, and the host's overview works as before. The roles, access tokens of an OAuth 2.0 issuer in place of the token, and how to keep set-up on the server itself are in rookery serve.

Edit on GitHub

Last updated on

On this page