install.md

September 20, 2026 · View on GitHub

acpx is published to npm as acpx. It is a single Node CLI — no service to host, no daemon to manage. Session state lives under ~/.acpx/.

Requirements

To run the published CLI: Node.js 22.13 or newer (see engines.node in package.json).
To build from source: Node.js 22.x starting at 22.22.1, 24.x starting at 24.11, or 26 or newer. lint-staged sets the Node 22 minimum; the tsdown build tool does not support Node 25. Published CLI installs still support Node 22.13 and newer.
pnpm 11.26.0 for source builds
The underlying coding agent CLI you plan to talk to (Codex, Claude, etc.)

If pnpm is not installed yet, use npm:

npm install -g pnpm@11.26.0

Some older Corepack builds bundled with supported Node.js versions have stale package-signing keys and fail while preparing current pnpm releases. Installing pnpm with npm avoids that bootstrap failure.

acpx itself does not need a global install of every adapter. Built-in adapters that ship as npm packages (pi-acp, @agentclientprotocol/codex-acp, @agentclientprotocol/claude-agent-acp, @kilocode/cli, opencode-ai, mux) are auto-fetched with npx on first use. The fast-agent built-in uses uvx fast-agent-mcp acp, so it requires uvx on PATH. Native CLI built-ins require their upstream CLI to be installed and authenticated separately.

Global install (recommended)

npm install -g acpx@latest

Verify:

acpx --version
acpx --help

Global installation puts acpx on PATH for repeated use.

Run without installing

npx acpx@latest codex exec 'fix the failing tests'

npx works for one-off use but pays a small startup cost on every invocation. For repeated session reuse, prefer the global install.

Update

npm install -g acpx@latest

Check what changed in the changelog. Pre-1.0 releases can break CLI/runtime surface area between minor versions.

Where data lives

Path	What it stores
`~/.acpx/sessions/*.json`	Persistent session records (scope key, last prompt, history previews, model, options)
`/tmp/acpx-<home-hash>/<session-hash>.sock`	Unix socket for an active queue owner
`~/.acpx/queues/<session-hash>.lock`	Queue-owner lease and process metadata
`~/.acpx/flows/runs/<runId>/`	Persisted flow run bundles (graph state, ACP transcripts, artifacts)
`~/.acpx/config.json`	Optional global config (see Config)
`<cwd>/.acpxrc.json`	Optional project config (merged on top of global, CLI flags still win)

Windows uses a named pipe instead of a Unix socket. The socket directory hash is derived from the home directory; the socket and lease filenames use a hash of the session record id.

Queue and IPC directories are created with owner-only permissions. acpx re-tightens permissions on previously-permissive directories at startup.

Build from source

For development or to test an unreleased branch:

git clone https://github.com/openclaw/acpx.git
cd acpx
npm install -g pnpm@11.26.0 # if pnpm is not already installed
pnpm install
pnpm run build
node dist/cli.js --help

Run during development without rebuilding:

pnpm dev codex 'fix the tests'

See CONTRIBUTING.md for tests, lint, and the conformance suite.

Tell your agent about acpx

If you are configuring an upstream coding agent (Pi, OpenClaw, Claude Code) to delegate work through acpx, paste this block into its harness instructions:

I want you to use acpx to run coding agents over the Agent Client Protocol
(ACP) instead of scraping PTY sessions. Please do the following:

1. Install acpx globally (recommended) or use npx:
   npm install -g acpx@latest

2. For Pi or OpenClaw, use the reference URL below. For Codex-style skill
   installation, install the acpx skill so you have the full reference
   available:
   npx acpx@latest --skill install acpx --agent codex --scope user
   Use --agent claude for Claude Code. For another harness not listed by
   --skill install --help, use the reference URL below instead.

3. Read the acpx skill reference so you know every command, flag, and
   workflow pattern:
   https://raw.githubusercontent.com/openclaw/acpx/main/skills/acpx/SKILL.md

4. Full CLI reference with all options and examples:
   https://acpx.sh/CLI.html

From now on, when you need to delegate work to a coding agent, use acpx
instead of spawning raw terminal sessions.

Next steps

Quickstart — your first persistent session in two minutes.
Agents — every built-in agent name and what it wraps.
Config — global + project JSON config.