box
The command on every host for the agent's side of Rookery, from desktop control to actions, the channel and services.
box is installed on every host as /usr/local/bin/box. It talks to rookeryd at agent level and works from any shell of the agent, including those of the coding agents and of T3 Code.
box desktop screenshot [--output PATH|-] | click X Y [BUTTON] | type TEXT | key CHORD | scroll up|down [STEPS] | clipboard | pause | resume
box mcp the desktop tools as an MCP server on stdio
box exec [COMMAND...] run a command, or a shell, with the desktop's environment
box actions the actions this user may run
box run ACTION [NAME=VALUE...] run one; output here, its exit code as box's
box publish TOPIC [JSON] [--keep none|last|log]
box listen TOPIC-PREFIX [--since ID] one JSON message per line
box services what can be called, and whether it is up
box call SERVICE METHOD [JSON] result on stdout
box serve SERVICE -- COMMAND... per call: COMMAND METHOD, body on stdin, result on stdout
box --version the versionDesktop
box desktop controls the agent's shared desktop. It enters the desktop's environment by itself, so it works from any shell of the agent.
box desktop screenshot --output /srv/agent/artifacts/screen.png
box desktop click 300 250
box desktop type "Hello"
box desktop key ctrl+l
box desktop scroll down 3
box desktop clipboard
box desktop pause
box desktop resumeEach subcommand also takes its arguments as JSON with --args, as in box desktop click --args '{"x":300,"y":250}'.
Input is serialized per call, and pause blocks cooperating tools until resume. It is not a scheduler: only one GUI task should use the desktop at a time. T3 Code stays usable for coding if the desktop fails.
Desktop tools for other clients
box mcp offers the same tools as a stdio MCP server: screenshot, click, typing, key chords, scroll and clipboard read. The plugins that install a coding agent register it for the agent when they are installed. For another client, merge /etc/rookery/mcp.json into its configuration, or register it as Claude Code would:
claude mcp add --transport stdio --scope user desktop -- /usr/local/bin/box mcpDesktop environment
box exec runs a command with the desktop's display, Xauthority, session bus and tool PATH. Without a command it starts a shell. GUI programs and commands T3 starts already share that environment. Ordinary SSH shells need box exec.
box exec firefox https://example.com
box exec glxinfo -B
box exec xvfb-run -a COMMAND
box exec rookery-smokeActions
box actions lists the host's actions the agent may run, those marked agent: true, and box run runs one with its plugin steps:
box actions
box run smoke
box run sign-in:statusChannel
The channel passes JSON messages between programs on the host and Rookery. Topics of plugins are PLUGIN/TOPIC; --keep overrides how long a message is kept (none, last or log).
box publish myplugin/progress '{"percent": 40}' --keep last
box listen myplugin/
box listen myplugin/ --since 120From your machine, rookery channel listen HOST PREFIX follows the same messages.
Services
box services
box call ask/desk ask '{"question":"Which branch do I release from?"}'
box serve ask/desk -- /opt/ask/handlerSee Writing a service for box serve.
Last updated on