Quickstart: your agent on real work

Build a custom harness, run a synthetic session locally, then install it and send it real work. You need Git, Node.js 20 or newer, and the One Horizon CLI:

npm i -g @onehorizon/cli

1. Scaffold a harness

one harness init my-agent --template typescriptcd my-agentnpm install && npm run build     # the manifest points at dist/, so build before the first run

Templates: typescript, python, pydantic-ai, and acp-bare. The TypeScript, Python, and bare templates are small protocol fixtures. The Pydantic AI template uses the framework's ACP harness, roots filesystem and shell tools in the task workspace, connects the supplied stdio MCP server, and reads its model and provider key from your environment.

The worker reads the one.json manifest:

{  "name": "my-agent",  "displayName": "My Agent",  "version": "0.1.0",  "protocol": "acp",  "command": ["node", "dist/agent.js"],  "unsupportedModes": ["plan", "research", "review"]}

The generated agent handles initialize, session/new, and session/prompt over newline-delimited JSON-RPC. It emits one agent_message_chunk update and returns end_turn. Keep stdout reserved for ACP messages; write diagnostics to stderr.

2. Bring your real agent

Your real implementation needs to consume the MCP servers supplied in session/new, preserve the trusted and untrusted prompt framing, and read its own model credentials. The worker owns auth and polling.

Already have an ACP agent? Skip the scaffold and install its local command directly:

one auth loginone harness install 'acp:gemini --acp'

The command must start an ACP agent on stdio. The consent screen shows the exact argv as JSON before anything executes; control and bidirectional formatting characters are rejected. See the ACP contract.

OpenCode, Mistral Vibe, Hermes, Cline, DeepSeek Harness, and OMP already ship as ACP presets, so you do not need to build a harness for them. Local agents covers their setup.

3. Iterate locally

one harness dev

dev spawns your agent in a scratch workspace and drives one synthetic turn over ACP. Nothing is registered and no workspace data is loaded. The agent itself is not sandboxed and may still use the network. Rebuild after edits; dev spawns whatever the manifest command points at.

Exercise another supported mode while developing:

one harness dev --mode plan

After one auth login, replay a task through the production prompt assembly without updating or claiming it:

one harness dev --task tskAb12Cd34 --mode code

4. Install and register

A harness is the software you just built. An agent is a registered instance of it that picks up work. Install the first, create the second.

one harness install checks the vendor CLI, ACP protocol negotiation, and session creation without sending a prompt.

1. 1

   Sign in once per machine

   one auth login opens the browser sign-in. Skip this if the CLI is already authenticated.

2. 2

   Install the harness

   one harness install ./ fetches the current harness policy, reads the manifest, then runs your doctor command if you declared one (see the manifest reference). A stale or unavailable policy stops installation. After the checks pass, the harness appears in one agent create and Desktop's Add-agent picker next to Codex, Claude Code, and Cursor.

3. 3

   Create the agent

   one agent create registers a user-owned agent and asks two things: which harness, and which repository (projectRoot) this agent works in. Task worktrees are created from that local clone using your own git setup; One Horizon never needs your git credentials. You never call the API.

The agent is bound to this machine and repository; to use another machine, install the harness there and create a second agent.

5. Give it work

one agent watch          # pick up work in the foreground; Ctrl+C to stop

Then send it something: open any initiative, bug, or todo in the dashboard and select Send to... → your agent. To run a single task without watch, use:

one agent run tskAb12Cd34

Watch the live activity and outcome on the task. Plan and usage details appear only when the agent reports them. When it looks right, run it as a background daemon with one agent start.