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:
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-keyWithout 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:
sudo tailscale serve --bg --https=443 http://127.0.0.1:7777Connect 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 machineWith 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 lsROOKERY_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:
docker exec rookery rookery server setup-key # or: rookery server setup-keyIt 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.netRookery 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.
| Address | Reaches |
|---|---|
https://HOST[:PORT] | A server behind a TLS proxy |
http://HOST:PORT | A server's port directly |
unix:/path/to/serve.sock | A 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 | iexOn macOS:
curl -fsSL https://raw.githubusercontent.com/aiviarium/rookery/main/install.sh | shEach 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 uiRookery 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.
| Variable | Effect |
|---|---|
ROOKERY_SERVER | The server, for this run |
ROOKERY_TOKEN | The token, so it isn't asked for |
ROOKERY_FILE | The 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 machine | Why |
|---|---|
| Writing the USB installer to a drive | The drive is a device of that machine |
rookery ssh HOST | It uses that machine's SSH configuration and keys |
rookery registry publish and rookery registry push-image | They upload files of that machine |
rookery server … and rookery serve | They are the server itself |
| The settings that aren't open to the network | The 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 setandrookery host importsave the profile there. - A password the server generates is kept there.
rookery host credentials HOSTasks the server for it. rookery apply HOSTand Apply this configuration run as a job on the server. Rookery follows its output as it comes (Jobs).rookery host seed HOSThas the server render the cloud-init seed, and writes it here.rookery host create HOST --provisioner NAME,rookery host startandrookery host stopuse the server's provisioners and secrets (Provisioners).rookery resourceuses 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 secrettailnet_api_keyare the server's, which creates the keys its hosts join with and looks after their devices. Settings androokery config setchange them there. - A plugin is installed on the server, and its features show on the Features tab of the server's hosts. A
.tgzor 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 keyacts on the server's ring, and its private halves stay there.rookery key trust HOSTandrookery host verify HOST --acceptmake first contact and accept a changed host key from the server. rookery key rotatereplaces 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.
Last updated on
Nodes
A node is a server that Rookery applies without a desktop, such as one that hosts Incus and Docker machines. Creating one, taking in a server that exists, and what Rookery leaves to you.
The store
Where Rookery keeps its state, how to put it in PostgreSQL and encrypt it, and how to move or restore an installation.