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", "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. one runtime install runs a real turn for every declared mode, and every one of them must pass or the install fails. Declaring plan commits your agent to writing plan blocks, research to writing research blocks without changing repository state, and review to calling report_workflow_verdict; 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 | Path to a local SVG or PNG, resolved relative to the resolved manifest directory. A symlink in runtimes.d resolves through to the real package directory; a plain copy of just the JSON resolves relative paths against runtimes.d itself, so the asset must sit beside that copy at the same relative path. Desktop's Add-agent picker shows SVG or PNG locally as a data URI for preview only. When the agent is created (CLI or Desktop), a valid SVG is uploaded once through the agent-icon endpoint and stored as AgentProfile.avatarUrl for the workspace. PNG is never uploaded. Detection and every later agent watch / agent start do not re-upload. See Icon requirements. |
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.
- Shared with the workspace: SVG only. 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 mentionsicon contains element <image>, which is outside the safe SVG whitelistmeans this rule fired. - Theme tip: prefer a small square
viewBoxsuch as0 0 24 24and usecurrentColorfor fill/stroke so the icon themes with the rest of the product.
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 declaredmodesand capabilities, because workflow routing and audit need them. Your launchcommand,args,env, paths, and source location never leave the machine. The one intentional exception is a valid SVGicon: its bytes are uploaded once at agent create so the whole workspace can render the same avatar. - 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
credentialEnvand 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.jsonAfter 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.