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. Custom runtimes support plan, research, code, review, and resolve conflicts — and any future task mode — unless the manifest explicitly excludes it.

Installation itself only runs a bounded ACP initialize/session/new compatibility check on the machine that installs the runtime; it never spends model credits and never produces verified_modes. Full per-mode conformance (one runtime dev --mode <mode>) is a separate, explicit diagnostic you or a release process invokes on demand. Only the resulting verified_modes and eligibility attestation, when they exist, are sent to One Horizon — the platform does not re-run conformance itself, and verification records local evidence only; it never narrows the modes a workflow may publish. Runtime policy and health are checked when One Horizon selects an executor.

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 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.
`unsupportedModes`	no	Modes this runtime cannot execute: any of `plan`, `research`, `code`, `review`, `resolve_conflicts`. Missing or empty means every current and future task mode is eligible. Installation runs a bounded ACP initialize/session handshake; per-mode conformance is optional diagnostic evidence, never a routing prerequisite. See documents and tools.
`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`.
`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, unsupported and locally verified modes, and capabilities. Workflow routing and audit need this projection. 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.