Skip to Content

On the host

Where Rookery puts things on a host, and what an agent finds there to learn about the machine.

Files

AGENT.md
expected-commands
mcp.json
environment
rookeryd.json
actions.json
services.json
channels.json
applied.json
profile.json
PathHolds
/etc/rookery/AGENT.mdThe 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-commandsCommands the self-test requires, including those plugins list
/etc/rookery/mcp.jsonThe desktop MCP server, to merge into an MCP client's configuration
/etc/rookery/*.jsonrookeryd's settings, actions, services and channel topics
/etc/rookery/applied.jsonThe versions of Rookery and its plugins at the last apply
/etc/rookery/profile.jsonThe 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-stateThe state of the first-boot provisioning
/var/lib/rookery/readyWritten when Ansible converged, with the release's digest
/var/lib/rookery/toolchains.jsonThe 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.envSecrets given as environment variables
~/.config/tigervnc/passwordThe desktop's password
/srv/agent/workspaces, /srv/agent/artifactsWhere agents keep projects and output, such as screenshots

Services

UnitRuns
rookeryd.servicerookeryd, as root
rookery-svc-PLUGIN-NAME.serviceOne per plugin service
rookery-provision.serviceThe first-boot provisioning of a USB or cloud install, with a retry timer
The agent's user servicesThe 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:

AgentFile
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 smoke

The browser check starts Playwright's Chromium with its sandbox on. How Chromium sandboxes itself depends on the machine:

MachineSandbox
Laptop, server or virtual machineA user namespace, which an AppArmor profile of the role allows
Container, such as one from Incus or DockerChromium'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.

Edit on GitHub

Last updated on

On this page