acpx/docs/install.md

title	description
Install	Install acpx globally with npm, run it ad-hoc with npx, or build from source. Covers Node version, PATH, and updating.

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

• Node.js 22.12 or newer (see engines.node in package.json)
• The underlying coding agent CLI you plan to talk to (Codex, Claude, etc.)

acpx itself does not need a global install of every adapter. Built-in adapters that ship as npm packages (pi-acp, @zed-industries/codex-acp, @agentclientprotocol/claude-agent-acp, @kilocode/cli, opencode-ai) are auto-fetched with npx on first use.

Global install (recommended)

npm install -g acpx@latest

Verify:

acpx --version
acpx --help

Global install is the default for most workflows because it keeps queue owners and persistent sessions warm between invocations.

Run without installing

npx acpx@latest codex '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)
~/.acpx/queues/<hash>.sock	Unix socket for active queue owners (named pipe on Windows)
~/.acpx/queues/<hash>.lock	Ownership lock file
~/.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)

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
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. Install the acpx skill so you have the full reference available:
   npx acpx@latest --skill install acpx

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.