Config

acpx is configurable through two JSON files. CLI flags always win over config, and project config wins over global.

#Files and precedence

1. Global   ~/.acpx/config.json
2. Project  <cwd>/.acpxrc.json
3. CLI flags

Each layer is a partial override merged on top of the previous one. Missing keys inherit; arrays and objects are replaced, not deep-merged (with the exception of the agents map, where keys merge and per-agent objects replace wholesale).

Inspect the resolved view:

acpx config show

Create a global template (only writes if the file does not already exist):

acpx config init

#Supported keys

{
  "defaultAgent": "codex",
  "defaultPermissions": "approve-all",
  "nonInteractivePermissions": "deny",
  "authPolicy": "skip",
  "ttl": 300,
  "timeout": null,
  "format": "text",
  "mcpServers": [
    {
      "name": "local-tools",
      "type": "stdio",
      "command": "./bin/mcp-server"
    }
  ],
  "agents": {
    "my-custom": { "argv": ["./bin/my-acp-server", "acp"] }
  },
  "auth": {
    "openai_api_key": "sk-…"
  }
}

CLI flags always override these values. For example, --approve-all wins over defaultPermissions: "deny-all".

Use --mcp-config <path> when MCP servers belong to a session or automation job rather than the working tree. The file must contain the same top-level mcpServers array shown above; it replaces the project/global mcpServers value for that invocation. Relative paths resolve from --cwd.

acpx --cwd /workspace --mcp-config /run/job-mcp.json codex 'use the configured tools'

An existing persistent session cannot switch MCP configurations while its queue owner is live. Close that session first, then retry with the new --mcp-config file.

#The agents map

Custom agents and overrides live here:

{
  "agents": {
    "my-agent": {
      "argv": ["./bin/my-acp-server", "acp", "--profile", "ci"]
    },
    "codex": {
      "argv": ["/usr/local/bin/codex-acp", "--mode", "stable"]
    }
  }
}

Rules:

• Keys are friendly names you would type at acpx <name> ….
• argv is the preferred form and is required for custom agent launches on Windows. Its first item is the executable and every remaining item is passed literally as one argument.
• Legacy { "command": "…", "args": […] } entries migrate when command is an unquoted executable with no whitespace. Quoted executables and inline arguments are rejected as ambiguous; move the complete launch to argv.
• A legacy command without args remains a raw command string for Unix compatibility. Windows rejects it with migration guidance because inferring argv would corrupt paths and quoting.
• The raw --agent <command> escape hatch is likewise Unix-only.
• Windows cannot execute .sh files directly. Name the interpreter explicitly, for example "argv": ["bash", "C:\\tools\\bin\\agent.sh"]; acpx does not discover or infer an interpreter.
• On Windows, close and recreate custom-agent sessions created by an older acpx release so their records persist structured argv. Known built-in commands migrate automatically.
• An entry that shares a name with a built-in replaces the built-in for that name.

Project config can shadow global config by re-declaring the same key:

{ "agents": { "codex": { "argv": ["/usr/local/bin/codex-acp"] } } }

Use this to point a particular repo at a vendored or pinned adapter.

#Authentication

ACP authenticate handshakes need credentials. acpx resolves them from two sources, in order:

1. ACPX_AUTH_<METHOD_ID> environment variable, where <METHOD_ID> is the upper-cased ACP auth-method id.
2. auth.<methodId> value in config.

ACPX_AUTH_OPENAI_API_KEY=sk-… acpx codex 'do the thing'

{ "auth": { "openai_api_key": "sk-…" } }

Ambient provider env vars like OPENAI_API_KEY are still passed through to child agents in their environment, but they do not trigger ACP auth-method selection on their own. This is intentional — it avoids surprise login flows in adapters that interpret an ambient key as "go ahead and authenticate."

When an adapter advertises auth methods, acpx invokes authenticate if it finds a matching ACPX_AUTH_* environment variable or auth config value. authPolicy controls what happens when no matching credential is available:

#Environment variables

ACPX_CLAUDE_INCLUDE_USER_SETTINGS=1 makes built-in claude sessions include Claude Code user settings. By default, they load only project and local settings to avoid globally enabled channel or daemon plugins interfering with spawned ACP sessions.

Other ACP-relevant behavior:

• Session storage path is derived from the OS home directory (~/.acpx/sessions).
• Child adapter processes inherit the current environment by default.
• Some adapters look at their own env vars (e.g., QODER_PERSONAL_ACCESS_TOKEN) — see Agents for per-adapter notes.

#Practical config recipes

#Make CI fail rather than deny

{
  "defaultPermissions": "approve-reads",
  "nonInteractivePermissions": "fail",
  "format": "json"
}

#Default to Claude with a longer timeout

{
  "defaultAgent": "claude",
  "timeout": 1800,
  "ttl": 0
}

#Vendor an internal Codex build for one repo

<repo>/.acpxrc.json:

{
  "agents": {
    "codex": {
      "command": "/opt/internal/codex-acp",
      "args": ["--profile", "internal-stable"]
    }
  }
}

#Pin a custom agent name without colliding with a built-in

{
  "agents": {
    "ci-bot": {
      "command": "node ./scripts/ci-acp-bridge.mjs"
    }
  }
}

Then acpx ci-bot 'run sanity checks' resolves through the registry without any --agent flag.

#See also

• Agents — built-in registry and per-agent notes.
• Custom agents — --agent escape hatch and unknown positional names.
• Permissions — defaultPermissions and non-interactive policy.
• Output formats — format default and --json-strict.