Build your own agent
The One Horizon worker runs coding agents against your queued work. Codex, Claude Code, and Cursor are built in. Your own agent can sit beside them: you own the model and tooling; the worker owns auth, sessions, and monitoring.
Custom agent harnesses require a paid plan.
The contract is the Agent Client Protocol (ACP), the open standard Zed and JetBrains use to host external agents. If your agent already speaks ACP, add a small manifest and install it locally. If it does not, use its framework's ACP adapter.
ACP coding agents can run every One Horizon task mode by default, including Plan, Research, Code, Review, and Resolve Conflicts. List a mode in unsupportedModes only if your harness genuinely cannot do it.
What the worker does for you
For an installed harness, the worker owns:
| Concern | Handled by |
|---|---|
| User sign-in and tokens | Worker (OAuth, secure storage, refresh) |
| Agent registration and identity | Worker (one agent create) |
| Finding work: polling, claiming, leases | Worker |
| Heartbeats, health, stall detection | Worker |
| Git worktree isolation per task | Worker |
| Prompt assembly with trusted/untrusted separation | Worker |
| Workflow documents, review verdicts, platform actions | Injected MCP tools |
| Activity feed, plans, token usage in the dashboard | Worker, from your ACP update stream |
| Terminal outcomes (complete / fail / release) | Worker, from your stop reason |
| Restarts, background daemon, Desktop lifecycle | Worker |
Your agent receives one turn at a time: the worker spawns your process, speaks ACP over stdio, and passes the working directory and an MCP server with One Horizon tools.
flowchart LR Queue["Queued session"] --> Host["Worker<br/>(auth, claim, worktree)"] Host <-->|"ACP over stdio"| Agent["Your ACP agent"] Agent <-->|"MCP tools"| Host Host -->|"activity, plans, tokens, outcome"| Dashboard["One Horizon"]
How this fits your machines
- A harness is installed software, cataloged per machine and per OS user.
- An agent is a registered instance of a harness, bound to the machine and repository where you created it. Your agents are visible from any dashboard; each one runs only on its own machine.
- One machine can hold many harnesses. One harness can back many agents, typically one per repository.
- The same harness may be at different versions on different machines. Each agent's details page shows the harness version and manifest digest that executes its work.
Working from two machines means installing the harness on both and creating an agent on each. There is no remote start: a machine runs only what its owner started there.
Three ways in
Scaffold a harness. one harness init writes a TypeScript, Python, Pydantic AI, or bare ACP fixture plus a one.json manifest. Start at the quickstart.
Existing ACP agent. Add a one.json manifest, or install a local command with acp: such as gemini --acp. The ACP contract lists the headless behaviors the worker relies on.
Ship a harness product. Distribute a manifest with your local installer or a repository users clone. Remote package sources and signed-publisher resolution are covered on the distribution page; only local path and local ACP command installs are in the public install flow today.
Enforced boundaries
- Agents never see user OAuth tokens. Tool access uses a short-lived, session-scoped MCP token.
- Turn and stall timeouts are host-enforced. A hung agent is terminated and the session retried or failed per policy.
- The spawn environment is allowlisted. Your process receives the variables it needs, not the user's whole environment.
- Permission requests (
session/request_permission) are answered by host policy. There is no human at this keyboard. - Trusted platform instructions and untrusted task content arrive as separately marked content blocks. Agents must not promote untrusted text to instructions.
A harness is trusted local software with the user's OS permissions, like any tool they install. The protections above bound what a harness can do to One Horizon; they are not an OS sandbox around the process itself.
Cloud agents
For a shared, always-on service on your own infrastructure, build a cloud agent against the REST API with webhooks. It uses the same trusted/untrusted prompt structure, MCP tools (over HTTP), and outcome vocabulary; only work delivery differs, because a cloud agent claims sessions from the API instead of receiving turns over ACP.
Cloud agents authenticate through an OAuth app. Manage the client from Settings → Apps and inspect the callback and client type before copying credentials into your service configuration.