Proxmox lifecycle

Template model

Build an immutable, stopped, unprivileged LXC template with deploy/build-workspace-template.sh. It includes the workspace user, SSH server, language and build tools, supported agent binaries, and required runner dependencies. Do not put repositories or credentials in the template.

Use a non-root agent user and the fixed checkout path:

/workspace/repo

Rebuild templates rather than editing them in place. Linked clones use the template's ZFS base snapshot, so edits to a live template dataset do not reach new workspaces. See Proxmox setup for the first-build and rebuild commands.

Creation

For each request, the controller:

1. Records the workspace and ownership token.
2. Allocates a VMID and creates a linked clone in the configured pool.
3. Waits for clone and start tasks, then discovers its DHCP address.
4. Verifies SSH, installs runtime credentials, and bootstraps the workspace.
5. Checks out the requested repository and ref, writes seed files, and starts the selected runner.
6. Sends the purpose and marks the workspace ready.

Every external task ID is persisted. If a response is lost or the controller restarts, it reconciles with Proxmox before retrying.

Destruction

Deletion records the desired state first, stops the LXC, re-reads its ownership marker, then purges the container. An already-absent container is success.

Reconciliation

At startup and periodically, the controller resumes unfinished operations, checks stored task IDs, and compares the workspace pool with its records. Containers with an unknown or mismatched ownership marker are reported as orphans; they are never removed automatically. This protects live work after a database restore or loss.

Common failures