Distribute your runtime

A runtime is distributable the moment its repository or package contains a valid one.json. There is no submission process, no build step on our side, and no server-side registration by you. Installation is a local, user-consented action.

Today users can install from a local directory, enable a detected runtimes.d manifest, or install a local ACP command — through the CLI, Desktop, or a one://runtime/install?source=... deep link. Git, npm, PyPI, named registry, ACP registry, and Sigstore verification are not in the public install flow yet, so a deep link naming one of those sources still fails at resolution; only local-path and acp: sources actually install today.

Install sources

For a manifest install, the manifest is validated, static requirements are checked, consent is collected, doctor runs, and the entry is added to the machine catalog. An acp: install creates an inert code-only manifest for the argv you entered, then follows the same consent and conformance path. Neither form uses a shell to launch the command.

The installed runtime appears in one agent create and Desktop's Add-agent picker. npx @onehorizon/cli runtime install ./ uses the same implementation without a global CLI install.

Desktop accepts a local source through Agents → Add agent → Add runtime, which opens a short explainer and a file picker for one.json, or via a one://runtime/install?source=... deep link that opens the same picker pre-filled. Remote sources (git/npm/PyPI/registry) are not enabled regardless of which entry point you use.

After you choose a runtime (or select a detected one), Desktop shows a Review step with the same layout whether the runtime still needs consent or is already enabled: publisher, exact launch command, and what it can access. Enabling is digest-bound; nothing executes before consent.

Zero-touch discovery

If your product has its own installer, skip even the install command: write your manifest into the drop-in directory.

~/.one/runtimes.d/conductor.json        # macOS/Linux (per-user)%APPDATA%\One\runtimes.d\conductor.json # Windows

Desktop and the CLI scan this directory. The next time the user opens Add agent, your runtime appears badged "Detected on this machine". Detection grants nothing by itself: enabling shows your publisher, version, and exact launch command, and requires the user's consent. Remove the file on uninstall and the entry disappears.

This is how your runtime becomes an option in One Horizon without One Horizon ever having heard of you.

Bundling inside your own product

If your app ships its own installer, bundle the integration:

1. Ship one.json inside your app bundle.
2. After your own install completes, run one runtime install <path-to-manifest-dir>, or hand off to Desktop with a one://runtime/install?source=<path-to-manifest-dir> deep link so the user finishes consent in the picker.
3. Optionally run one agent create --runtime conductor --non-interactive to take the user straight to a working agent. The browser-based sign-in is the only human step, and only if they weren't signed in already.

Your users never need to learn what ACP is. They click "Connect One Horizon" in your app and their queued work starts flowing to your agent.

Versioning and updates

• The catalog records the manifest version at install time; it is shown on the agent details page and in one runtime list.
• one runtime update [name] re-reads an installed local source and records new consent before the next turn.
• Desktop does not yet resolve runtime updates. Use one runtime update [name] for an installed local source; it never updates a third-party runtime without new consent.
• Updates are per machine: a user with agents on two machines updates each catalog separately, and the same runtime can legitimately run different versions on different machines in the meantime. Each agent's details page shows the exact version and manifest digest executing its work.
• Breaking changes in your agent's behavior deserve a major version bump: workflow authors pin expectations to what your runtime does, not just to its API surface.

Trust and safety

A runtime process runs with the user's OS permissions, the same trust level as any software they install, including the built-in agent binaries. One Horizon's job is honest presentation at the moment of consent, not gatekeeping what a user may run on their own machine.

• Detected is not trusted. Entries discovered via runtimes.d appear as "Unverified — found on this machine", never with a badge. The consent screen shows the publisher, version, terms links, and the exact command that will run. Nothing executes before the user enables it.
• Consent is digest-bound. Enabling snapshots the manifest digest and resolved launch argv. Desktop displays the argv as JSON so spaces cannot hide argument boundaries, and rejects control or bidirectional formatting characters. If the manifest or launch digest changes later, the runtime is paused and the consent screen returns.
• Permission requests during a turn. Agents run unattended, so ACP session/request_permission is answered automatically by host policy — there is no human prompt mid-turn. On the Review step, When the agent asks for extra permissions lets the user choose Deny requests (recommended) or Allow one-time requests. Built-in Agent access (Read-only / Workspace access / Full access) is a separate trust boundary for Codex, Claude, and Cursor.
• Checks are compare-and-swap protected. Every post-consent check has a unique transaction ID. A stale install or update cannot commit or roll back over a newer consented candidate.
• No impersonation by naming. A detected manifest whose name or displayName collides with a built-in runtime or one already installed on the machine is not shown at all.
• Block and revocation policy. The worker evaluates runtime ID, name, manifest, launch, command-pattern, and publisher-revocation rules. It projects only an expiring eligibility result; blocked, unknown, and stale runtimes cannot register, schedule, or claim work.
• Verified modes are client-attested. Conformance for plan/research/code/review modes runs locally during one runtime install; the platform stores whatever result the CLI/Desktop client reports and does not independently re-run or re-verify it. "Verified" means the local client observed a passing conformance run, not platform-side verification.
• Publisher verification. Publisher verification is not in the public install flow yet. Unsigned local runtimes stay explicitly unverified.
• Drop-in folder. Software able to write to runtimes.d is already running code as the user. The folder grants visibility in the picker, not capability. The mitigations above make sure nothing borrows One Horizon's UI to look more legitimate than it is.

A note on names

Catalog names are machine-local, so there is no global name race. displayName is what users see; make it match your brand. Keep name stable: changing it orphans existing agents' runtime references and forces users to re-create agents.