ACP (Agent-Client Protocol) Setup Runbook
Ultimate Harness provides native support for ACP v1 (Agent-Client Protocol), allowing UH to orchestrate external ACP-compliant agent processes (e.g. OpenHands, Zed agents, or custom ACP servers) through standard JSON-RPC 2.0 over standard I/O.
1. Prerequisites
Section titled “1. Prerequisites”- An executable agent that implements ACP v1 (reads JSON-RPC on
stdin, writes onstdout). - The agent command accessible in
PATHor configured viaserver_command.
2. Adapter Configuration
Section titled “2. Adapter Configuration”The adapter manifest is located at .harness/adapters/acp.yaml.
schema_version: uh.adapter.v0id: acpname: Agent-Client Protocol (ACP)description: Native ACP v1 runner for headless agent orchestrationruntime: acpcapabilities: - cli-execution - json-output - diff-outputstatus: activeconfig: server_command: acp-agent server_args: [] protocol_version: 1 timeout_ms: 600000Runtime Configuration Options
Section titled “Runtime Configuration Options”server_command(string, default:"acp-agent"): The binary or script invoked by UH.server_args(string[], default:[]): Command line arguments passed to the ACP server.protocol_version(integer, default:1): ACP protocol version (v1).timeout_ms(integer, default:600000): Per-request timeout in milliseconds.mcp_servers(array, default:[]): MCP servers advertised to the agent insession/new. Each entry is either a stdio server ({ name, command, args?, env? }) or an HTTP server ({ type: "http", name, url, headers? }). UH maps these to the ACP v1 wire shape and never writes serverenvorheadersvalues into any artifact.env(object, default:{ set: {}, drop: [] }): Environment policy for the agent process.dropremoves exact variable names orNAME_PREFIX*patterns from a copy ofprocess.env;setthen adds/replaces values, sosetwins overdrop. Names compare case-insensitively on Windows. Values are never written into any artifact.
A value in mcp_servers headers or env, or in env.set, may contain ${NAME}, which UH replaces from the environment when the run starts. Keep tokens that way: the adapter file then names the variable and never holds the secret, and a variable that is not set stops the run with a message naming it. Set the variable in your shell, not in a file under the project.
config: server_command: prime-agent server_args: ["--mode", "acp"] mcp_servers: - name: files command: npx args: ["-y", "@modelcontextprotocol/server-filesystem"] env: FS_ROOT: . - type: http name: remote url: https://example.test/mcp headers: Authorization: "Bearer ${ACP_MCP_TOKEN}" env: set: DO_NOT_TRACK: "1" drop: - "ORCA_*"3. Mission Usage
Section titled “3. Mission Usage”Single Mission
Section titled “Single Mission”In your mission packet:
schema_version: uh.mission.v0id: sample-acp-missiontitle: "Run task via ACP"workflow_profile: bugfix-containedruntime_config_overrides: server_command: my-acp-binary timeout_ms: 300000Execute with:
uh mission run .harness/missions/sample-acp-mission/mission.yaml --runtime acpTeam Mission
Section titled “Team Mission”ACP is also a first-class team worker adapter:
schema_version: uh.mission.v0id: sample-team-acpshape: teamteam: leader: adapter: command-code role: leader workers: - adapter: acp role: worker-acp objective: "Implement headless task via ACP"4. Verification and Governance
Section titled “4. Verification and Governance”When UH executes an ACP mission:
- It validates the ACP handshake (
initialize). - Spawns the agent within the isolated sandbox boundary.
- Services agent-to-client permission requests (
session/request_permission) according to harness policy. - Records canonical run facts (
runtime-result.yaml,diff.patch,stdout,stderr, andruns/index.json).