pve-agents

Give it a repository, a ref, and a purpose. It clones a golden template, boots an LXC, checks the repository out, starts a Claude Code agent inside it and hands it the purpose. The web UI streams that agent's transcript, takes prompts, answers its permission dialogs, shows what it changed, and pushes or discards the result. When a workspace has outlived its usefulness the controller destroys it — unless it is holding work nobody kept.

The controller owns the lifecycle, the policy and the UI. Proxmox owns the containers. Claude Code owns the actual work.

                You, in a browser
                        │
                        ▼
                pve-agents :3000
   request · stream · approve · diff · push · reap
           │                          │
           ▼                          ▼
     Proxmox API                 workspace LXC
 clone · boot · destroy      Claude Code · git checkout

Built for one operator on a trusted LAN. It holds a Proxmox token, a GitHub App key and a Claude subscription token, and it creates and destroys real containers.

What it does

• Start work from a sentence — a repository, a ref and a purpose become a booted container with an agent already working in it. No step in between is yours.
• Watch the agent think — the transcript streams over SSE, tool calls and all, replayed from the beginning for whoever opens the page late.
• Answer its questions — permission prompts surface in the browser and are answered there, rather than in a terminal somebody has to already be attached to.
• Read what changed — per-file diffs in the rail, then push to pve-agents/<hostname> or discard the lot.
• Drop into a real shell — a full terminal into the workspace over ghostty-web, for the things a transcript cannot do.
• Forget about cleanup — idle workspaces are reaped automatically, and a workspace holding uncommitted or unpushed work is exempt until you deal with it.
• Keep Proxmox honest — containers the controller no longer recognises are reported, never destroyed. A restored database does not cost you your fleet.
• Lock it down — GitHub sign-in for the UI, hashed API keys for machines.

What you need

• A Proxmox host, with an API token, a pool, and a golden template built by deploy/build-workspace-template.sh. The controller runs against its API; it does not have to run on the host itself.
• RAM on that host to match how many workspaces you want at once. Each one is a real LXC running a checkout and a Claude Code agent, so the ceiling on parallelism is the memory you are willing to give them. Size a single container in the template, decide how many you want live, and multiply — the controller will happily ask for more than the host can seat.
• Disk is cheaper than it looks. Containers are linked clones of one ZFS snapshot, so the template's bulk (the Agent SDK alone is about 245 MB) is paid once for the whole fleet rather than per workspace.
• Node 22+ and pnpm, wherever the controller runs.
• A GitHub App, so the controller clones and pushes as an installation rather than as you.
• A Claude subscription token, from claude setup-token. Not an API key.

None of that is needed to try the UI. With PROVISIONING_ENABLED off — which is the default — a request queues a durable operation and builds nothing, so the whole state machine can be exercised without a hypervisor anywhere near it. See the quick start.

Where to go next