Architecture

Each workspace request names a repository, ref, configured agent, and purpose. The controller creates a disposable Proxmox LXC, checks out the repository, starts the selected agent, and sends it the purpose. The container is disposable; the work is preserved by pushing it to a branch.

Browser or API → controller → Proxmox API → workspace LXC
                    │                         │
                    └── SSH ── agent runner ──┘

Responsibilities

The controller holds the Proxmox token and GitHub App key. Workspaces receive only the short-lived repository credential and the credential for their selected agent.

User interface

The dashboard shows a workspace's conversation, approvals, timeline, changes, and a separate shell. Conversation updates stream over server-sent events. Tool calls that the agent does not resolve itself become browser approvals, where an operator can approve or deny them with an explanation.

The Terminal tab opens a separate ssh -tt login. It is intentionally not the agent's session, so inspection commands cannot interfere with work in progress.

Lifecycle and recovery

Workspace operations are durable and advance in small persisted steps. A restarted controller resumes from the recorded operation, Proxmox task IDs, and observed container state instead of starting again. See provisioning.

Ready workspaces are checked for activity and Git state. Reaping is optional and never destroys a workspace that is blocked, has uncommitted or unpushed work, or cannot be inspected. The controller also reports unrecognised containers but never deletes them automatically.

Freshness

The fleet list reads controller state frequently, activity checks refresh ready workspaces on their configured interval, and an open workspace page streams live updates. Observations from an open page are saved before other readers consume them, keeping controls and status in agreement.