pve-agentsRequirements
What you need before the controller can build real containers.
To go past the queue and build real containers:
- Node 22+ and pnpm
- A Proxmox host with an API token, a pool, and a template built by
deploy/build-workspace-template.sh - A GitHub App, for cloning and pushing as an installation rather than as you
- A credential for at least one coding agent — a Claude subscription token, or an opencode one
Proxmox setup walks the hypervisor side of that in order, including the two things that are easy to reach the end without: the controller's SSH key, and the first template.
The template
Start from an immutable, stopped, unprivileged LXC template, intentionally large enough to avoid package installation during provisioning. See the template model for what goes in it and why editing a template in place does not work.
You do not need one already. deploy/build-workspace-template.sh builds the first from a stock
Ubuntu 24.04 image, and every one after that from the template in service.
The two GitHub credentials
GITHUB_APP_* and GITHUB_CLIENT_* are different credentials with different purposes, and they
are easy to confuse:
GITHUB_APP_* | How the controller clones and pushes — as an installation, not as a person. |
GITHUB_CLIENT_* | How you sign in to the UI. Nothing else uses it. |
The agent credential
Not an environment variable. Agents are configured in the Agents tab, each with its own credential, and a workspace cannot be launched until there is at least one.
For Claude Code the credential comes from claude setup-token, which needs a browser and a Claude
subscription. It is not an API key. opencode takes a JSON envelope instead. Which agents a build can
drive is its own topic.
Last updated on