Run and monitor your harness
Once installed and registered, a custom harness shows up in the same agent and task views as the built-in ones. How much detail appears depends on what your harness emits: activity, tool calls, usage, summaries, artifacts, and outcomes. The dashboard shows the harness name, version, manifest digest, and compatibility level, never its launch command or paths.
Each harness shows a compatibility level: Connected, Tools connected, Code verified, Plan/review verified, or Telemetry available. Installation only establishes Connected. The level is informational and does not change which modes the harness is offered.
Process model
The worker is the long-lived process: started by Desktop or one agent start, sending heartbeats, polling for eligible sessions, claiming work. Your agent process exists only during turns, spawned per turn and terminated after the stop reason. Consequences:
- Your agent needs no daemon behavior, signal handling beyond normal termination, or restart logic.
- Machine restarts, Desktop updates, and agent restarts (Desktop's restart controls, or
one agent stopfollowed byone agent start) are invisible to you. The host re-establishes everything and your process is simply spawned again on the next turn. - Crash isolation is per turn: an agent crash fails that turn, with your stderr captured in the session log, and never takes down the worker.
Agents are machine-bound: the dashboard shows all of them, but starting, stopping, and restarting happen on the agent's own machine.
Monitoring in the dashboard
The host surfaces what it learns from your ACP updates:
| Surface | Shows |
|---|---|
| Agents page | Harness name, version, online/offline, active turns, queue depth |
| Agent details | Health history, recent sessions, configured settings, harness version and manifest digest, compatibility level |
| Task / run view | Live activity from your message chunks, the plan panel from your plan updates, tool-call transcript |
| Session outcome | Terminal state with your summary; failures link the session log |
| Usage | Context size and cumulative cost from your usage_update notifications. Input, output, and total tokens from the usage on each session/prompt response. The model from your model config option, with your harness as the model provider. See the ACP contract for how tokens are counted |
Stalls and failures also raise the standard workflow notifications.
Logs
one agent logs prints the last 50 lines of the worker log and then follows new output: claiming, spawning, and outcomes. Per-session detail, including your agent's captured stderr, is attached to the session in the dashboard.
one agent logsLog freely to stderr. stdout belongs to ACP; a stray print() to stdout is the most common conformance bug, and one harness dev catches it.
Upgrading safely
one harness update swaps versions between turns, never mid-turn. For harnesses you distribute to others, treat a turn as your compatibility unit: any version must be able to pick up any turn cold, because that is exactly what happens after every update, restart, and crash.
When something misbehaves, start from the symptom in troubleshooting.