Optional add-ons

The base image stays small. Add-ons install extra tools on a VM, at pinned versions.

Add-on	What you get	LLM gateway
`chrome`	Headless Chromium with CDP on `127.0.0.1:9222`, fonts, and Playwright/Puppeteer env	n/a
`codex`	OpenAI Codex CLI	Wired in `~/.codex/config.toml`
`claude-code`	Anthropic Claude Code CLI. `claude` is an alias.	Wired to the gateway in `~/.claude/settings.json`
`opencode`	opencode CLI	Wired in `~/.config/opencode/opencode.json`
`pi`	pi coding agent. Already in the base image; this pins or updates it.	Wired in `~/.pi/agent/models.json`
`desktop`	XFCE, reached in the browser at the VM’s URL (`/_agentcloud/desktop/`). Basic. Not a 60 fps desktop.	n/a
`dev`	Go on `PATH`, Node.js and npm, PostgreSQL on localhost.	n/a
`gemini`	Gemini CLI 0.64.0. A local install is estimated at 250 MiB.	You set `GEMINI_API_KEY` or `GOOGLE_API_KEY`. It does not speak the Turm gateway.
`aider`	Aider 0.86.2, installed with uv and CPython 3.12. Measured at about 750 MiB.	You supply your own key. It does not speak the Turm gateway.

ssh turm.dev addons list shows the current catalog with versions.

On the dashboard, the New VM form has a checkbox for each add-on. The desktop note stays hidden until that checkbox is checked. It is the same sentence as the VM welcome page.

Alpine 3.24’s Python is too new for aider-chat 0.86.2, so the guest installs CPython 3.12 with uv. aider together with desktop needs more disk than a new VM has free, and new refuses that pair.

Install on a new VM

ssh turm.dev new --name=agent --with=codex,chrome
ssh turm.dev new --name=desk --desktop
ssh turm.dev new --name=build --with=dev

Add-ons install on first boot.

Add or remove on a running VM

ssh turm.dev addons add agent opencode
ssh turm.dev addons rm agent chrome
ssh turm.dev addons ls agent

Changes apply within a minute. addons ls shows each add-on’s desired state, current state and installed version.

A VM with no heartbeat, older than a few minutes, and not created with --with is refused because its image is too old. A heartbeat of agentcloud-addon version 2 can add chrome, codex, claude-code, opencode, and pi. desktop, dev, gemini, and aider are refused, and the error names that version. A version 3 heartbeat can add desktop and dev. gemini and aider need version 4. Nothing on the VM is changed. Create a new VM with new --with, or replace /usr/local/bin/agentcloud-addon on that VM. The next sync reports the new version within a minute, and then the same command works.

From inside the VM

agentcloud-addon list
agentcloud-addon install codex
agentcloud-addon update codex
agentcloud-addon remove codex