pve-agentsAgents and harnesses
How the controller supports multiple coding-agent implementations.
A harness defines how the controller runs one kind of coding agent. Operators create configured agents in the Agents tab; each one chooses a harness, credential, and optional model.
What a harness provides
| Part | Purpose |
|---|---|
bootstrap | Files required for the agent to start unattended. |
credential | How its credential is validated and installed. |
merges | Seed files that must merge with bootstrap configuration. |
runner | The process that talks to the agent's API. |
readTranscript | Translation of agent events into the operator conversation. |
Harnesses register themselves by name. An unknown name fails rather than falling back to a default: the controller must never run an agent the caller did not select. The registry also limits the Types shown in Settings to the harnesses this controller build can run.
Included harnesses
claude-code runs through @anthropic-ai/claude-agent-sdk. Unresolved tool calls wait for the
browser approval flow. Its credential is an OAuth token from claude setup-token.
opencode2 runs a server on loopback and subscribes to its event bus. Its credential is a JSON envelope naming the integration; the runner writes it into opencode's credential store.
The controller uses the same workspace lifecycle and UI for both.
Kind versus configured agent
- A kind is a harness built into this release.
- A configured agent is an operator-created row with a name, kind, credential, and optional model. Several configured agents can share a kind.
A workspace records its configured agent when it is requested; there is no controller-wide default. Changing or deleting a configured agent affects only future workspaces. Running workspaces retain the runner and credential installed when they were provisioned.
Last updated on