Skip to Content
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

PartRuns onDoes
rookeryyour machineKeeps a profile per host and installs it. Manages hosts afterwards from its terminal UI or commands
The rolethe host, once per install or applyThe Ansible role that sets up the host. Every install method runs it
rookerydthe host, as rootRuns actions, sessions and services and answers the API
boxthe host, for the agentDesktop control, actions the agent may run, the channel and services, from the agent's side (box)
rookery serveyour machine or a serverOne API over all hosts, with an inbox and a key-value store. Other machines running Rookery can use its hosts (A Rookery server)
PluginbothCoding 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

TermMeaning
HostAnything Rookery reaches and logs in to, such as a laptop, server, VM or container
ProvisionerA plugin's way to create the machine for a host, such as a container on Docker or a VM on Incus. See Provisioners
TypeWhat Rookery does with a host: ssh only logs in, managed adds Rookery's controller, workstation applies the whole profile. See Host types
ProfileThe 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
TargetThe kind of machine a host is installed on, such as a laptop, a cloud machine or a container. A profile says it as target
OperatorYour account on the host, ops by default, for SSH and Cockpit
AgentThe 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
ActionSomething 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 levelrookeryd 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:

In the host's profile
{ "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

On this page