Build your own agent
The One Horizon worker runtime 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 runtime owns auth, sessions, and monitoring.
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. The One Horizon SDK helpers preserve turn metadata and trust markers; they do not replace an ACP server.
Local installs support code, plan, research, and review modes. Declare each mode in the manifest; one runtime install runs a real turn for every declared mode before the workflow router sends your agent that step.
What the worker runtime does for you
When your agent runs as an installed runtime, the worker runtime owns the operational surface:
| Concern | Handled by |
|---|---|
| User sign-in and tokens | Worker runtime (OAuth, secure storage, refresh) |
| Agent registration and identity | Worker runtime (one agent create) |
| Finding work: polling, claiming, leases | Worker runtime |
| Heartbeats, health, stall detection | Worker runtime |
| Git worktree isolation per task | Worker runtime |
| Prompt assembly with trusted/untrusted separation | Worker runtime |
| Workflow documents, review verdicts, platform actions | Injected MCP tools |
| Activity feed, plans, token usage in the dashboard | Worker runtime, from your ACP update stream |
| Terminal outcomes (complete / fail / release) | Worker runtime, from your stop reason |
| Restarts, background daemon, Desktop lifecycle | Worker runtime |
Your agent receives one turn at a time. The worker runtime spawns your process, speaks ACP over stdio, passes the working directory and an MCP server with One Horizon tools, streams your updates into the product, and maps your stop reason to a session outcome.
flowchart LR Queue["Queued session"] --> Host["Worker runtime<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 runtime is installed software, cataloged per machine and per OS user.
- An agent is a registered instance of a runtime, 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 runtimes. One runtime can back many agents, typically one per repository.
- The same runtime may be at different versions on different machines. Each agent's details page shows the runtime version and manifest digest that executes its work.
Working from two machines means installing the runtime 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
SDK helpers. @onehorizon/agent-sdk for TypeScript parses One Horizon turn context, keeps trusted and untrusted blocks separate, and reads agent-owned model credentials. Start at the quickstart. For Python, one runtime init --template pydantic-ai wires Pydantic AI Harness directly to the protocol — no separate One Horizon SDK needed.
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 runtime relies on.
Ship a runtime 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
The worker runtime bounds what a misbehaving agent can do to One Horizon:
- 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 runtime is trusted local software with the user's OS permissions, like any tool they install. The protections above bound what a runtime can do to One Horizon; they are not an OS sandbox around the process itself.
Cloud agents
For a shared, always-on service that serves a whole team from your own infrastructure, build a cloud agent against the REST API with webhooks. The semantic contract matches this page: the same trusted/untrusted prompt structure, the same MCP tools over HTTP, the same outcome vocabulary. Only work delivery differs: locally the worker runtime hands you turns over ACP; in the cloud you claim them from the API.
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.