Quickstart: your agent on real work

Build a custom runtime, watch it execute a synthetic session locally, then install it and send it real work. The path works with the npm CLI or Desktop. Templates cover TypeScript, Python, Pydantic AI, and a bare ACP fixture; release builds also ship a standalone CLI binary for machines without Node.js.

You need Git and the One Horizon CLI:

npm i -g @onehorizon/cli

1. Scaffold a runtime

one runtime init my-agent --template typescriptcd my-agentnpm install && npm run build     # the manifest points at dist/ — 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.

one.json — the manifest the worker runtime reads:

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

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

The demo agent is a stand-in. Your 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 platform does not add auth or polling code to your agent; the worker owns those concerns.

Already have an ACP agent, or want to use a stock one like OpenCode or Gemini CLI? Skip the scaffold and install its local command directly:

one loginone runtime 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.

3. Iterate locally

one runtime 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 declared mode while developing:

one runtime dev --mode plan

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

one runtime dev --task tskAb12Cd34 --mode code

4. Install and register

A runtime 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 runtime install runs conformance for every mode listed in modes. The workflow router only sends your agent a plan, research, or review step after that mode passes.

1. 1

   Sign in once per machine

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

2. 2

   Install the runtime

   one runtime install ./ fetches the current runtime 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 runtime 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 runtime, 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 run the same runtime on another machine, install it there and create a second agent. Both show up in the dashboard, and each runs where it lives.

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 use Send to → your agent, or from the terminal:

one send tskAb12Cd34 --agent my-agent

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.