Run and monitor your runtime
Once installed and registered, a custom runtime uses the existing agent and task surfaces. How much appears depends on the updates the runtime emits: activity, tool calls, usage when emitted, summaries, artifacts, and terminal outcomes. Runtime identity, version, manifest digest, compatibility, and eligibility are projected without exposing machine launch details.
Every runtime carries a compatibility level — ACP connected → tools connected → code verified → plan/review verified → telemetry available. Installation records verification for each declared mode only after the consented runtime completes conformance for it; development turns do not change the installed catalog.
Process model
The worker runtime 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.
Across machines: agents are machine-bound. The dashboard shows all your agents everywhere, but starting, stopping, and restarting happen on the agent's own machine. An agent that is offline because its machine is asleep cannot be woken from the dashboard; that is the design, not a failure.
Monitoring in the dashboard
Everything the host learns from your ACP updates is surfaced without any work on your side:
| Surface | Shows |
|---|---|
| Agents page | Runtime name, version, online/offline, active turns, queue depth |
| Agent details | Health history, recent sessions, configured settings, runtime 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; per-turn token breakdowns when your agent emits them |
Stalls and failures also raise the standard workflow notifications. Users learn about a stuck run from One Horizon, not from tailing your logs.
Logs
Two commands, three layers of information, outermost first:
one agent logs # 1. worker runtime: claiming, spawning, outcomesone agent logs --session ses_9XkQ # 2. per session: ACP traffic summary # 3. …including your agent's captured stderr
Your agent's stderr is yours: log freely, it is captured per turn and attached to the session log. stdout belongs to ACP; a stray print() to stdout is the classic conformance bug, and one runtime dev catches it.
Upgrading safely
one runtime update swaps versions between turns, never mid-turn. For runtimes 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.