Getting started
How it fits together
The parts of Rookery, where each one runs, and the words the rest of the docs use.
Rookery has a side on your machine and a side on each host. Your machine installs and manages hosts. Each host runs a small controller, and the agents run there.
your machine a host
┌──────────────────────────┐ SSH ┌──────────────────────────────────┐
│ rookery (terminal UI, CLI)│ ───────▶ │ rookeryd root daemon, API │
│ profiles, secrets │ │ box for the agent │
│ rookery serve (local API) │ │ desktop, plugins and their agents │
└──────────────────────────┘ └──────────────────────────────────┘The parts
| Part | Runs on | Does |
|---|---|---|
rookery | your machine | Keeps a profile per host and installs it. Manages hosts afterwards from its terminal UI or commands |
| The role | the host, once per install or apply | The Ansible role that sets up the host. Every install method runs it |
rookeryd | the host, as root | Runs actions, sessions and services and answers the API |
box | the host, for the agent | Desktop control, actions the agent may run, the channel and services, from the agent's side (box) |
rookery serve | your machine or a server | One API over all hosts, with an inbox and a key-value store. Other machines running Rookery can use its hosts (A Rookery server) |
| Plugin | both | Coding agents, provisioners, other software, actions and services, switched on per host (Plugins) |
Rookery's own files and settings on a host carry its name, such as /etc/rookery and the rookery_ variables.
Words used in these docs
| Term | Meaning |
|---|---|
| Host | Anything Rookery reaches and logs in to, such as a laptop, server, VM or container |
| Provisioner | A plugin's way to create the machine for a host, such as a container on Docker or a VM on Incus. See Provisioners |
| Type | What Rookery does with a host: ssh only logs in, managed adds Rookery's controller, workstation applies the whole profile. See Host types |
| Profile | The JSON document that describes one host, from what to install to how it is reached, or a template to start one from. Rookery keeps it in its store. See Profile |
| Target | The kind of machine a host is installed on, such as a laptop, a cloud machine or a container. A profile says it as target |
| Operator | Your account on the host, ops by default, for SSH and Cockpit |
| Agent | The account the coding agents, which plugins install, work in, agent by default. The virtual desktop runs as this account. Its sudo rights are its privileges |
| Action | Something a host, a provisioner, a resource or the installation can do. A host's controller has actions such as Status or a sign-in, run from its overview or with rookery run HOST ACTION. Plugins add actions |
| Host level, agent level | rookeryd answers on two sockets. Rookery connects at host level, as root. box connects at agent level, as the agent. Each call says which levels may use it |
Connecting to a host
Rookery connects to a host by running ssh HOST sudo -n rookeryd connect and talking HTTP to rookeryd over that connection. Several requests share one SSH connection. A profile can name another command instead in access.link, which is how a container is reached:
{ "builder": { "link": ["docker", "exec", "-i", "CONTAINER", "rookeryd", "connect"] } }When the SSH user's sudo asks for a password, Rookery asks you once and keeps it until it closes.
Edit on GitHub
Last updated on