Your first workspace

A workspace request needs an enabled agent, repository, ref, and purpose. The purpose is sent to the agent verbatim, so state the outcome you want rather than prescribing every implementation step.

Request work

Use the dashboard launch form, or the API:

curl -X POST http://127.0.0.1:3000/api/workspaces   -H "x-api-key: $PVE_AGENTS_KEY"   -H "content-type: application/json"   -d '{"idempotencyKey":"first-try","harnessId":"<agent ID>","repository":"github.com/you/your-repo","ref":"main","purpose":"Find out why the nightly job leaves orphans behind"}'

The request queues immediately. Run pnpm worker:tick to advance it once, or pnpm worker:tick --watch 5 while testing. When infrastructure is verified, set WORKER_ENABLED=true to run the worker in the server process.

Follow the work

The conversation streams tool calls and agent messages. When an agent needs an approval that its own configuration does not resolve, approve or deny it in the browser. The Timeline records prompts, approvals, pushes, and discards.

Use Diff to inspect changed and untracked files. The Terminal tab is a separate SSH login for running commands in the workspace; it does not send keystrokes to the agent session. On a touch screen a row of keys under the terminal supplies Esc, Tab, Ctrl and the arrows, which a phone keyboard lacks.

On a phone the conversation fills the screen. The workspace list opens from the menu button at the left of the bar and the rail from the panel button at the right. Both are full-screen drawers, and the back gesture closes either one without leaving the page.

Keep or remove the result

• Push commits changes to pve-agents/<hostname>, never the checked-out ref.
• Discard resets uncommitted changes after confirmation; existing commits remain.
• Destroy removes the workspace when you are done.

Reaping can remove idle workspaces when enabled in Settings. It never removes workspaces that are blocked, have uncommitted or unpushed work, or cannot be inspected.