Harness manifest
one.json lives at the root of your harness's repository or package. It is the only file One Horizon needs to make your agent installable: one harness install resolves a source, reads this manifest, and adds the harness to the machine's catalog.
The CLI and Desktop validate the manifest, resolve relative launch paths against its directory, and bind consent to the canonical manifest and launch digests.
Installing runs a quick ACP initialize and session/new check on the installing machine. It does not send a prompt or spend model credits. Per-mode checks with one harness dev --mode <mode> are an optional diagnostic you run yourself; their results never change which modes a workflow can use.
Minimal manifest
{ "name": "my-agent", "displayName": "My Agent", "version": "0.1.0", "protocol": "acp", "command": ["node", "dist/agent.js"]}
Full manifest
{ "$schema": "https://onehorizon.ai/docs/schemas/one.json", "name": "conductor", "displayName": "Conductor", "version": "1.4.2", "description": "Conductor's multi-model coding agent.", "publisher": "Conductor Inc.", "homepage": "https://conductor.dev", "icon": "./assets/icon.svg", "iconLight": "./assets/icon-light.svg", "iconDark": "./assets/icon-dark.svg", "protocol": "acp", "command": ["conductor", "agent", "--acp"], "env": { "CONDUCTOR_MODE": "one-horizon" }, "credentialEnv": ["CONDUCTOR_API_KEY"], "unsupportedModes": [], "doctor": ["conductor", "--version"], "requires": { "binaries": ["conductor"] }, "termsUrl": "https://conductor.dev/terms", "privacyUrl": "https://conductor.dev/privacy", "supportUrl": "https://conductor.dev/support"}
The $schema reference gives editor autocomplete and CI validation.
Field reference
| Field | Required | Meaning |
|---|---|---|
name | yes | Stable identifier, kebab-case, unique per machine catalog. Shown in one agent create --harness <name>. |
displayName | yes | Human name shown in Desktop's Add-agent picker and the dashboard. |
version | yes | Semver. Reported on the agent details page; used by one harness update. |
protocol | yes | "acp" is the only supported value. Protocol version negotiation happens inside ACP's initialize, not here. |
command | yes | Argv array that starts your ACP agent speaking JSON-RPC on stdio. An array, never a shell string. Relative paths resolve against the manifest directory. |
env | no | Non-secret defaults for the spawned process. Never put credentials here because this file is committed. Keys must not start with ONE_WORKER_. |
credentialEnv | no | Environment variable names whose machine-local values the user consents to pass to the harness. Values never enter the manifest or control plane. One Horizon and GitHub credential names are rejected. |
unsupportedModes | no | Modes this harness cannot execute: any of plan, research, code, review, resolve_conflicts, execute. Missing or empty means every current and future task mode is eligible. See ACP contract. |
modes | no | Legacy supported-mode list. The installer translates modes omitted from this list into unsupportedModes. Do not set both fields. New manifests should use unsupportedModes. |
authFailureMarkers | no | Literal, case-insensitive substrings that identify a missing-login failure from your agent, captured from a real signed-out run. When one matches, setup stops before creating an agent and tells the user to sign in with your CLI, linking supportUrl or homepage. Without this field a sign-in failure is reported as a connection failure. At most 12 markers, each 3-64 characters of letters, digits, spaces, - and _, containing at least one letter or digit, no duplicates. Matching is a bounded word-boundary scan over the first 8 KB of failure text: 401 will not match inside 4013 ms. Patterns are deliberately not accepted, so no manifest can make classification expensive. |
authFailureSurface | no | Where your agent's missing-credential failure first appears: setup (the default) if it refuses initialize or session/new while signed out, or first_prompt if it accepts the handshake with no credential and only fails once a turn starts. Declaring first_prompt makes One Horizon send one bounded probe prompt during readiness inspection (no MCP servers, every permission request denied, cancelled as soon as it answers), so a signed-out agent is caught before an agent is created instead of failing the user's first task. The probe fails closed: if the turn has not settled within 20 seconds it is cancelled and readiness is reported as unknown, which stops setup, because silence is not evidence of a credential. Declare it from an observed signed-out run, not from expectation, and only if your agent answers a one-word prompt well inside that window. |
doctor | no | Argv array the host runs during install and one agent doctor. Exit 0 means healthy; stdout is shown to the user on failure. |
requires.binaries | no | Binaries that must be on PATH at install time. Checked before doctor. |
description, publisher, homepage | no | Catalog and picker presentation. publisher is shown prominently on the consent screen when a user enables your harness. |
icon | no | Default path to a local SVG or PNG. One Horizon uses it when the current theme has no matching icon. See Icon requirements. |
iconLight, iconDark | no | Paths to icons for light and dark interfaces. Each matching icon takes precedence over icon; omit either field to use the default. |
termsUrl, privacyUrl, supportUrl | no | Linked from the consent screen and the harness's catalog entry. The usage relationship is between you and the user; state your terms where they decide. |
Icon requirements
Valid SVGs from all three icon fields are uploaded when the agent is created so the whole workspace sees them. PNG is accepted for local Desktop preview and is never uploaded. Uploaded icons must be genuine vector SVG, not a bitmap wrapped in an SVG shell.
- Icon paths resolve relative to the manifest directory. If you copy
one.json, copy every referenced icon at the same relative path. iconLightappears on light interfaces andiconDarkon dark ones; keepiconas the theme-neutral fallback.- 64 KB decoded maximum.
- No
<script>, no event-handler attributes (onload, and similar), and no<image>elements: embedding or referencing a raster bitmap is rejected. A failure that mentionsicon contains element <image>, which is outside the safe SVG whitelistmeans this rule fired. - Prefer a small square
viewBoxsuch as0 0 24 24.
What the manifest is not
When a user creates an agent, One Horizon receives only a projection of the manifest for workflow routing and audit: harness ID, name, version, a manifest digest, unsupported and locally verified modes, and capabilities. Your launch command, args, env, paths, and source location never leave the machine; valid SVG icons are the only files uploaded.
The manifest grants no permissions. Your process runs with the invoking user's OS permissions, the same as built-in harnesses. Platform credentials never enter the process, and only values named in credentialEnv and approved during consent are inherited from the machine.
The manifest is not a prompt either: agent behavior, system prompts, and model choice stay in your harness.
Validation
one harness install and one harness dev validate the manifest against the published JSON schema and fail with line-level errors. CI can do the same:
one harness validate ./one.jsonAfter install, one harness doctor <name> re-runs the declared doctor command for a cataloged harness without touching any agent; one agent doctor runs the same check in a registered agent's real launch environment.