On the host
Where Rookery puts things on a host, and what an agent finds there to learn about the machine.
Files
| Path | Holds |
|---|---|
/etc/rookery/AGENT.md | The description of the machine for agents (below) |
/etc/rookery/guides/ | Longer guides for the desktop, graphics, and each plugin feature with a guide |
/etc/rookery/expected-commands | Commands the self-test requires, including those plugins list |
/etc/rookery/mcp.json | The desktop MCP server, to merge into an MCP client's configuration |
/etc/rookery/*.json | rookeryd's settings, actions, services and channel topics |
/etc/rookery/applied.json | The versions of Rookery and its plugins at the last apply |
/etc/rookery/profile.json | The host's profile, for root only, which another Rookery can adopt |
/usr/local/lib/rookery/tasks/ | The scripts of Rookery's own actions |
/var/lib/rookery/provision-state | The state of the first-boot provisioning |
/var/lib/rookery/ready | Written when Ansible converged, with the release's digest |
/var/lib/rookery/toolchains.json | The runtime versions that were installed |
/var/lib/rookeryd/ | rookeryd's state: session transcripts and the kept channel messages |
/run/rookery/ | rookeryd's sockets, host level and agent level |
~/.config/rookery/secrets.env | Secrets given as environment variables |
~/.config/tigervnc/password | The desktop's password |
/srv/agent/workspaces, /srv/agent/artifacts | Where agents keep projects and output, such as screenshots |
Services
| Unit | Runs |
|---|---|
rookeryd.service | rookeryd, as root |
rookery-svc-PLUGIN-NAME.service | One per plugin service |
rookery-provision.service | The first-boot provisioning of a USB or cloud install, with a retry timer |
| The agent's user services | The virtual desktop, noVNC and, when a plugin installed it, T3 Code |
What agents read
/etc/rookery/AGENT.md is generated on each host from what was installed there. It lists the tool categories, the coding agents and the CPU or GPU rendering, with one line per plugin feature. It stays short and points to /etc/rookery/guides/ for the rest.
When a plugin installs a coding agent, the agent's own instruction file points to it, without overwriting existing text. The files are:
| Agent | File |
|---|---|
| Claude Code | ~/.claude/CLAUDE.md |
| Codex | ~/.codex/AGENTS.md |
| Pi | ~/.pi/agent/AGENTS.md |
GUI programs, and T3 Code and the commands it starts, share the desktop's DISPLAY, Xauthority and session bus. Ordinary shell commands get them with box exec.
The self-test
rookery-smoke is the Self-Test action. It checks:
- that the expected commands exist
- llvmpipe on the shared desktop and in Xvfb, and lavapipe enumeration
- that the coding clients start with
--version - the desktop, browsers and artifact tools
- whatever the host's plugins add
It saves graphics reports and screenshots in its artifact directory.
rookery run studio smokeThe browser check starts Playwright's Chromium with its sandbox on. How Chromium sandboxes itself depends on the machine:
| Machine | Sandbox |
|---|---|
| Laptop, server or virtual machine | A user namespace, which an AppArmor profile of the role allows |
| Container, such as one from Incus or Docker | Chromium's setuid helper, which the role puts beside the Chromium it installs |
A container can't use the user namespace, because Ubuntu's AppArmor on the machine that runs the container takes away the rights Chromium needs in it. A Chromium that the agent installs itself in a container has no helper, so it can't start sandboxed. When the sandbox can't start, the check says so, names the kind of machine and fails. Chromium's own output is in browser-error.txt in the artifact directory. The container image runs under Docker's default seccomp profile, where neither way works, and there the check is listed as skipped.
Last updated on