Runtime manifest

one.json lives at the root of your runtime's repository or package. It is the only file One Horizon needs to make your agent installable: one runtime install resolves a source, reads this manifest, and adds the runtime 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. Installed custom runtimes route plan, research, code, and review steps once they declare the mode here and pass conformance for it.

Conformance runs entirely on the machine that installs the runtime, and only the resulting verified_modes and eligibility attestation are sent to One Horizon — the platform does not re-run conformance itself. "Verified" therefore means "the local CLI/Desktop client observed a passing conformance run," not that One Horizon independently validated the runtime. Treat this the same as any other trust decision you delegate to a machine you control.

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"],
  "modes": ["plan", "research", "code", "review"],
  "doctor": ["conductor", "--version"],  "requires": {    "binaries": ["conductor"]  },
  "termsUrl": "https://conductor.dev/terms",  "privacyUrl": "https://conductor.dev/privacy",  "supportUrl": "https://conductor.dev/support"}

The manifest is JSON because installers write it and machines read it. JSON parses unambiguously in every language, and the $schema reference gives editor autocomplete and CI validation for free.

Field reference

Field	Required	Meaning
`name`	yes	Stable identifier, kebab-case, unique per machine catalog. Shown in `one agent create --runtime <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 runtime 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 runtime. Values never enter the manifest or control plane. One Horizon and GitHub credential names are rejected.
`modes`	no	Task modes the runtime supports: any of `plan`, `research`, `code`, `review`. Default `["code"]`. Workflow routing only offers your agent steps in a mode after it is declared here and has passed conformance. User-installed runtimes run a real turn for every declared mode: `plan` requires `append_artifact_block` with `target=plan`, `code` requires `report_result`, `review` requires `report_workflow_verdict`, and `research` requires a research artifact block with no repository mutation. Curated and first-class ACP runtimes are code-only and use a bounded ACP initialize/session handshake instead. See documents and tools.
`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 runtime.
`icon`	no	Default path to a local SVG or PNG. One Horizon uses it when the current theme has no matching icon. When the agent is created, a valid SVG is uploaded and stored as `AgentProfile.avatarUrl` for the workspace. 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. Valid SVGs are uploaded and stored as `AgentProfile.avatarUrlLight` and `AgentProfile.avatarUrlDark`.
`termsUrl`, `privacyUrl`, `supportUrl`	no	Linked from the consent screen and the runtime's catalog entry. The usage relationship is between you and the user; state your terms where they decide.

Icon requirements

Icons that leave the machine must be genuine vector SVG — not a bitmap wrapped in an SVG shell.

Paths: icon, iconLight, and iconDark resolve relative to the resolved manifest directory. If you copy one.json, copy every referenced icon at the same relative path.
Themes: provide contrast for the interface named by the field: iconLight appears on light surfaces and iconDark appears on dark surfaces. Keep icon as the theme-neutral fallback.
Shared with the workspace: valid SVGs from all three icon fields are uploaded when the agent is created. PNG is accepted for local Desktop preview and is never uploaded.
Size: 64 KB decoded maximum.
Markup allowlist: no <script>, no event-handler attributes (onload, and similar), and no <image> elements. Embedding or referencing a raster bitmap inside the SVG is rejected; the icon must be vector markup (paths, shapes, text). A failure that mentions icon contains element <image>, which is outside the safe SVG whitelist means this rule fired.
Canvas: prefer a small square viewBox such as 0 0 24 24.

What the manifest is not

Mostly not server configuration. When a user creates an agent, One Horizon receives a projection of the manifest: runtime ID, name, version, a manifest digest, and declared modes and capabilities, because workflow routing and audit need them. Your launch command, args, env, paths, and source location never leave the machine. Valid SVG icons are uploaded when the agent is created so the whole workspace can render the correct avatar for each theme.
Not a permission grant. Your process runs with the invoking user's OS permissions, the same as built-in runtimes. Platform credentials never enter the process. Only values named in credentialEnv and approved during consent are inherited from the machine.
Not a prompt. Agent behavior, system prompts, and model choice remain part of your runtime.

Validation

one runtime install and one runtime dev validate the manifest against the published JSON schema and fail with line-level errors. CI can do the same:

one runtime validate ./one.json

After install, one runtime doctor <name> re-runs the declared doctor command for a cataloged runtime without touching any agent; one agent doctor runs the same check in a registered agent's real launch environment.

MCP tools

Every MCP tool the worker runtime can register for a turn, generated straight from the runtime tool catalog.

ACP contract

How the worker runtime drives your agent over the Agent Client Protocol: turn lifecycle, headless behaviors, trust boundaries, and outcome mapping.

Reference

Reference runtime responsibilities, workflow context, artifact documents, environment variables, and API operation families.

Overview

Plug any ACP-compatible agent into the worker runtime. One Horizon handles auth, sessions, tools, and monitoring; you build the agent.