Troubleshoot custom runtimes and agents
Start from the symptom. Runtime problems (installed ACP agents) come first; the cloud agent REST API lifecycle is at the end. When you file a bug, include one agent logs --session <id>, the runtime version and manifest digest from agent details, and one one runtime dev run.
Install and discovery
one runtime install rejects the manifest
Run one runtime validate ./one.json and fix the line-level errors. Common mistakes: command written as a shell string instead of an argv array, a mode outside plan|research|code|review, or the manifest not at the resolved source root.
Install fails at the doctor step
Your tool's prerequisites are missing on this machine. Run the doctor command manually in a non-interactive shell (zsh -c 'conductor --version'); version managers initialized only in interactive shells are the usual cause.
The runtime is missing from Desktop or one agent create
one runtime list is the source of truth. Detected entries only appear from valid manifests in ~/.one/runtimes.d/, and a manifest whose name collides with a built-in or installed runtime is deliberately suppressed.
Sign-in and connectivity
The agent shows offline while the process runs
Check heartbeats: the daemon may have died after a logout or reboot, the CLI session may be expired (one login), or the machine clock is skewed. A session that went stale mid-work continues after the same agent reclaims it, or use Try again for a replacement run after inspecting prior activity.
Turns fail with the agent's own auth errors
The runtime's vendor login is separate from One Horizon sign-in. Re-authenticate with the vendor's tool (for example gemini or OpenCode login), then verify with one agent doctor. Model provider 401/403 errors mean your API key isn't reaching the process; a .env file or keychain works everywhere, plain shell exports don't reach the background daemon.
Turns and protocol
Turns fail instantly with a protocol violation
stdout is polluted or the process exits before initialize. stdout belongs to ACP; log to stderr (console.error, sys.stderr, eprintln!, Go's log). one runtime dev shows the first malformed line.
Turns time out with no activity
The agent worked silently past the stall window. Emit session/update while working; long tool calls should stream tool_call_update. Slow self-hosted models need the per-agent timeout settings raised.
review, research, or plan turns always fail
Review turns must call report_workflow_verdict; plan and research turns must write their declared document blocks with append_artifact_block. Research also fails if repository state changes during the turn. These tools are described in documents and tools. Turns for modes you never declared in the manifest never arrive at all.
The session parks as awaiting input
The agent refused (stopReason: refusal) or asked for input. The stated reason is shown to the user as a question; answering it resumes the session. Refusals are never auto-retried.
Git and worktrees
Workspace preparation fails
The agent's projectRoot must be a writable Git repository with a usable base branch, and it is fixed at agent creation; if the folder moved, create a new agent. Clean stale task worktrees with one agent worktrees remove <task-or-path>.
Forced worktree removal discards uncommitted changes. Preserve the branch and any required files before adding --force.
The branch pushed but no PR or MR appeared
PR/MR creation goes through the workspace's GitHub or GitLab integration, not the agent's credentials. Confirm the integration is connected and PR creation is enabled in the workflow; the linked work moves to In Review only after One Horizon creates the review.
Operations
Work is queued but the agent stays idle
Check the concurrency limit and machine resource pressure in one agent status, whether the work targets a different agent, whether the mode is declared, and whether the runtime is paused pending re-consent after a manifest change.
Works in one runtime dev, fails registered
The registered agent runs with an allowlisted spawn environment, not your interactive shell. one agent doctor runs your doctor check in the real launch environment and exposes PATH and version-manager differences.
Custom runtime FAQs
Cloud agents (REST API)
Cloud agents implement the session lifecycle directly. Keep the failed request, HTTP status, session state, active claim ID, and latest activity together while debugging.
Agent endpoints reject the token
Use an OAuth user access token with the required agent scopes. Workspace API keys cannot call agent execution endpoints.
Revoke any token written to logs, task text, comments, documents, or source control. Store replacement credentials in a secret manager or operating-system secure storage.
No webhook arrived, or a webhook arrived twice
Webhook delivery is a wake-up signal; polling is required recovery. Deduplicate by event ID, then fetch eligible sessions and claim them. Do not start execution from webhook contents alone.
Claim conflicts and rejected claimId
A conflict means another runtime owns the active claim, the session was cancelled, or your runtime is no longer eligible; stop processing that session. Every mutation after claim must include the current claimId.
A claimed session never leaves active
Every execution path must call complete, fail, or release. Use release only when the runtime stops before useful work. Review-mode sessions must set reviewVerdict to approve, feedback, or reject before completion.
The agent sessions page owns the full lifecycle, targeting, resume, and delegation contract.