ACP Agents

What it is

• One engine, many agents. Every installed agent rides one engine, acpAgents. Each one shows up in the engine picker under its own name.
• The list is the official one. It comes from the ACP registry (cdn.agentclientprotocol.com) and is saved on this computer, so it still shows when you are offline.
• Agents bill their own company. You use your own subscription or key with each agent, so Omniscio shows no spend for these sessions.

What the user sees

• Settings → Accounts → Other tools → ACP Agents — search box, one row per agent with its author, version and status, and a badge:
  • Verified download — a program download whose fingerprint the list publishes.
  • Pinned npm package — an npm package at an exact version.
  • Not supported yet — with the reason on the row.
• Install / Update / Remove per row, a switch for "Show in the engine picker", and key fields for agents that sign in with an API key.
• Allow ACP agent sessions — the master switch (on by default).
• The engine picker lists each installed, switched-on agent by name.

Where to find it

How to install an agent

1. Open Settings → Accounts, expand Other tools, then ACP Agents.
2. Search for the agent and press Install. Omniscio downloads it, checks it, unpacks it into its own folder and starts it once to learn how it signs in.
3. If the row says it needs a key, paste the key and press Save.
4. Start a new session and pick the agent in the engine picker.

How it behaves

What installs and what doesn't

The list offers	Installs?	Why
A program download with a published fingerprint (.zip, .tar.gz, or a bare program)	Yes	The download is checked against the fingerprint before it is unpacked.
A program download without a fingerprint	No	Owner decision 2026-10-30: unchecked code never runs.
An npm package pinned to an exact version	Yes	Installed once with npm into the agent's own folder; npm's release cooldown still applies.
A .tar.bz2 archive	Not yet	Format not supported in v1.
A Python (uvx) package	Not yet	Not supported in v1.

When an agent offers both a checked download and an npm package, the download wins (it needs no Node.js).

Signing in

• Agents that sign in through their own window — the first time a session needs it, the agent opens its own login. Nothing to set up in Omniscio.
• Agents that take an API key — key fields appear on the row after install. Keys are stored encrypted on this computer and only given to that agent.
• Agents that only offer a terminal login — not supported in v1 (see Limits).

Error states and fixes

What you see	What it means	Fix
"Available from <date> (your npm release cooldown)"	The pinned version is newer than your npm waiting period allows.	Install on or after that date.
"Node.js is needed to install this agent"	npm is not on this computer.	Install Node.js from Settings → Toolchain.
"Installed, but it couldn't start yet"	The agent installed but did not answer its first handshake.	Press Check again.
"Stop the N session(s) using this agent first"	Install, update and remove are refused while a session runs on that agent.	Stop those sessions, then retry.
"This chat is already running on one ACP agent"	A conversation can't switch to a different ACP agent.	Start a new session with the other agent.
"Sign in to <agent> in Settings → ACP Agents"	The agent reported it isn't signed in.	Add the key on its row, or finish the agent's own login.

Limits in v1

• Terminal login — the ACP spec's newest sign-in style (the agent runs a login command in a terminal) is not supported yet. This is the main follow-up.
• Model choice — each agent runs its own default model.
• Quick Launch — the Quick Launch picker does not list ACP agents yet; use the main engine picker.
• CLI spawn — /project/:name/new cannot start an ACP agent session.

For agents

How it works under the hood

• Registry reader — fetches the list, validates every agent on its own (one bad entry never blanks the list), caches it for a day and falls back to the cache offline.
• Classifier — decides per agent and per computer whether it installs, and why not.
• Installers — the download path streams the archive to disk while checking its sha256, unpacks into a staging folder with traversal and link entries refused, then moves it into place; the npm path runs npm install --prefix <folder> <name>@<exact version> and launches the package's .bin shim.
• Install record — one install.json per version plus an index, written atomically; the registry's per-agent environment values (auto-update kill switches, ACP-enable flags) are kept, minus anything that changes how a program loads code.
• Session — the session stores its agent in the existing carrier-instance field (custom_provider_id); the shared slim ACP client spawns the installed command with the agent's environment plus its stored keys.

Files

• src/main/services/engines/acp-agents/ — reader, classifier, installers, store, keys, service.
• src/main/process/acp-agents-acp-client.ts and src/main/services/engines/acp-agents-acp-session-manager.ts — the engine.
• src/main/services/toolchain/verified-archive.ts — shared checked download and safe unpack (also used by the Cua Driver installer).
• src/main/ipc/acp-agents-handlers.ts and src/main/services/cli/cli-server-acp-agents-routes.ts — the Settings channels (human-only) and the read-only CLI route.
• src/renderer/src/features/settings/sections/accounts/AcpAgentsSection.tsx — the card.
• Contract: .claude/memory/contracts/acp-agents-engine-contract.md.

CLI

GET /acp-agents   → { howToUse, agents: [...], fetchedAt, offline }

Read-only. Install, remove and keys are human-only.

Related

• Hermes provider and Kimi Code provider — the hand-wired ACP engines this one generalizes.
• AI providers.