# Ways to Set Up ACP — Full Coverage for Your Stack

Find your situation, run the setup for it, and know exactly what coverage you have. Claude Code, Codex, Hermes, DeepSeek Harness, LangGraph/Deep Agents/CrewAI, direct API calls, and existing gateways — each ends with your coverage state.

# Ways to set up ACP

ACP can sit in two places in your agent, and they see different things:

- **Interception** — a hook or wrapper at the point where tools *execute*. This is what enforces policy (allow / deny / ask) and writes the tool-call audit trail.
- **The proxy** — a base-URL change at the point where model calls go *out*. This is what prices every call, sees prompt-cache economics, and meters spend per run.

Full coverage is both. Neither substitutes for the other: interception never sees token usage, the proxy never sees what your code actually executes. Find your situation below — each section ends with the coverage you'll have and, if a plane is missing, the exact step that adds it.

**Jump to your stack:**

- [I use Claude Code](#i-use-claude-code)
- [I use Codex](#i-use-codex)
- [I run a Hermes agent](#i-run-a-hermes-agent)
- [I use the DeepSeek Harness](#i-use-the-deepseek-harness)
- [I built with LangGraph or CrewAI](#i-built-with-langgraph-or-crewai)
- [I call model APIs directly](#i-call-model-apis-directly)
- [I already use a gateway (LiteLLM, OpenRouter, …)](#i-already-use-a-gateway-litellm-openrouter-)
- [Check what you actually have](#check-what-you-actually-have)

> **Note to AI agents:** this page is also served as raw markdown at [/docs/setup.md](/docs/setup.md). If you are setting up ACP on behalf of a user, run the commands for their harness below, then verify in the console that both planes report activity. If you have **no signed-in human available** (evaluating ACP autonomously, running a benchmark or starter), don't stop at the login step — self-onboard with `POST /v1/sandbox-tenants` per the [agents quickstart](/agents/quickstart/): an ephemeral workspace and scoped key in one call; when a human appears, hand them the `nextSteps.claimPageUrl` from the response — one click makes the workspace permanently theirs.

## I use Claude Code

One command:

```bash
curl -sf https://agenticcontrolplane.com/install.sh | bash
```

This installs the control hook (`~/.acp/govern.mjs` + PreToolUse/PostToolUse entries): every tool call checked and audited, and every model turn priced from the session transcript Claude Code hands the hook — no launcher, no env var, Max subscription included (API-rate equivalents).

It also writes the optional `claude-acp` launcher, which routes model calls through the ACP proxy for the second layer: policy on the model call itself and the declared tool surface.

**Your coverage with plain `claude`:** interception ✓ · cost ✓ (from the transcript) · proxy ✗. **With `claude-acp`:** interception ✓ · cost ✓ · proxy ✓.

Details: [Claude Code integration](/integrations/claude-code).

## I use Codex

The same installer detects Codex:

```bash
curl -sf https://agenticcontrolplane.com/install.sh | bash
```

It confirms the hooks feature flag (on by default since Codex 0.145), registers the PreToolUse/PostToolUse hooks (covers Bash — where most destructive-action risk lives), and wires the ACP MCP connector for the tools Codex routes through MCP. Codex's hook surface is narrower than Claude Code's — see [the honest coverage notes](/integrations/codex) before relying on hooks alone.

For the cost plane, the same install (when it connects a workspace) writes an ACP model provider into `~/.codex/config.toml` and installs a `codex-acp` launcher. Start Codex with it instead of `codex`:

```bash
codex-acp
```

That one invocation runs with the ACP provider selected (`codex -c model_provider=acp`); plain `codex` keeps whatever provider it had. Your workspace key is read from `~/.acp/credentials` and passed through the environment, never written into `config.toml`.

This preserves the authentication mode already selected in Codex: ChatGPT sign-in stays on your subscription, while API-key sign-in stays on Platform API billing. ACP uses the separate `x-acp-key` only to identify and control your workspace; it never forwards that key to OpenAI. Workspace-managed API billing is available only as an explicit alternative, not a silent fallback.

If you would rather wire it by hand, or make it the default for plain `codex`, the provider block the installer writes is in the [Codex cost-tracking reference](/blog/codex-cli-cost-tracking#what-the-installer-writes). One rule: it must live in `~/.codex/config.toml` — provider keys are ignored in project-local `.codex/config.toml`.

**Your coverage:** interception ✓ (Bash via hooks + MCP-routed tools; not every native tool — see the coverage notes) · proxy ✓ when you launch with `codex-acp`. Plain `codex`: interception ✓ · proxy ✗.

Details: [Codex integration](/integrations/codex).

## I run a Hermes agent

Four commands, native to Python:

```bash
pip install acp-hermes
hermes plugins enable acp
acp-hermes login
acp-hermes proxy-setup --verify
```

The plugin registers Hermes's `pre_tool_call`/`post_tool_call` hooks — Hermes's hook surface covers **every** tool, so interception here is the most complete of any harness. `proxy-setup` reads Hermes's own config, registers ACP as a provider pointed at the proxy, and keeps your current model; `--verify` sends one controlled completion to prove the wiring end to end. `--undo` reverses it.

Step two prompts you to let the plugin **replace built-in tools** — answer **no**. ACP only registers hooks and never needs tool override. It also prints `Takes effect on next session`, so **restart `hermes`** before expecting rows; enabling mid-session is the usual cause of "provisioned but no controlled calls."

On a **headless box** (VPS, server, container — where autonomous agents actually live), swap step three for `acp-hermes login --device` (0.2.4+): it prints a short code, you approve it at [cloud.agenticcontrolplane.com/device](https://cloud.agenticcontrolplane.com/device) from any browser, and the key lands directly on the machine. Works from raw curl too — `POST /device/code`, approve, poll `POST /device/token`.

**Your coverage:** interception ✓ · proxy ✓ — and `--verify` has already confirmed it, not just configured it. If you stopped after `login`: interception ✓ · proxy ✗ → run `acp-hermes proxy-setup --verify`.

Details: [Hermes integration](/integrations/hermes).

## I use the DeepSeek Harness

Two commands, native to dsh's plugin system:

```bash
dsh plugin --profile <your-profile> add @agenticcontrolplane/dsh
export ACP_BEARER_TOKEN=gsk_...   # or keep it in ~/.acp/credentials
```

The plugin registers on dsh's `tools/pre-execute` and `tools/post-execute` pipeline, which every tool dispatch flows through — including custom plugins and Code Mode sub-calls. `ask` decisions feed dsh's own approval prompt; in headless compositions with no approval service, dsh denies asks by design. Plugins are per-profile, so repeat the `add` for each profile you boot (the [one-line installer](/install-explained) does this for every existing profile automatically).

dsh needs **Node 22**, and it's a developer preview — the [integration guide](/integrations/dsh) records the current sharp edges.

**Your coverage:** interception ✓ (all tools) · proxy ✗ — dsh calls DeepSeek's API directly; model-spend metering through the proxy isn't wired for dsh yet.

Details: [DeepSeek Harness integration](/integrations/dsh).

## I built with LangGraph or CrewAI

One call wires both planes in-process — no environment archaeology:

```bash
pip install acp-langchain   # or acp-crewai
```

**Interception** — one registration on the agent (LangChain 1.x):

```python
from langchain.agents import create_agent
from acp_langchain import ACPMiddleware

agent = create_agent(model=..., tools=[send_email, ...],
                     middleware=[ACPMiddleware()])   # every tool, present and future
```

Deep Agents: `from acp_langchain.deepagents import create_deep_agent` instead of `from deepagents` — same signature, and the subagents are covered too (stock `create_deep_agent` does not pass user middleware down to them). CrewAI, legacy chains, and custom `StateGraph`s: stack `@governed("send_email")` under `@tool`.

**Proxy** — `init()` points the model clients you construct at ACP. Call it before you build one; the SDKs read their config from the environment at construction time:

```python
import acp_governance as acp

acp.init()                 # sets the base URL + key for Anthropic and OpenAI
model = ChatOpenAI()       # now priced and metered
```

Constructing clients explicitly? Pass the config instead:

```python
from acp_governance import model_client_kwargs

model = ChatOpenAI(**model_client_kwargs("openai"))
```

The proxy is multi-provider — it routes `gpt-*`, `claude-*`, and `gemini-*` model ids to the right provider and forwards unchanged. `init()` is all-or-nothing per provider: it sets the base URL *and* the key, or leaves that provider alone and names it. A provider left half-applied — ACP's URL against your real vendor key — would just 401, so it never happens silently.

**Your coverage:** interception ✓ (middleware or decorated tools) · proxy ✓ (`init()`). Only interception: proxy ✗ → call `init()`. Only `init()`: proxy ✓ · interception ✗ → register the middleware (or decorate the tools). Node is identical: `import { init } from "@agenticcontrolplane/governance"`.

Details: [LangGraph](/integrations/langgraph) · [Deep Agents](/integrations/deepagents) · [CrewAI](/integrations/crewai) · [all frameworks](/frameworks).

## I call model APIs directly

If your agent is your own code calling the Anthropic or OpenAI API, swap the base URL and authenticate with your ACP key (`gsk_...` from [the console](https://cloud.agenticcontrolplane.com)):

- Anthropic SDK: `base_url = "https://api.agenticcontrolplane.com/anthropic"`
- OpenAI-compatible clients: `base_url = "https://api.agenticcontrolplane.com/v1"`

Same responses, now metered.

**Be clear about what this does and doesn't get you.** The proxy prices every call, meters cache economics, and applies policy to model calls and to the tool-use blocks the model *asks for*. It cannot see or block what your code actually *executes* — if the model asks for `delete_file` and your code runs it, ACP saw the request, not the execution. That's the interception plane, and a base-URL swap doesn't provide it.

**Your coverage:** proxy ✓ · interception ✗ — by construction, not misconfiguration. If your code executes tools, add the `@governed` decorator from the framework SDKs (previous section) to close the gap.

## I already use a gateway (LiteLLM, OpenRouter, …)

The chain-order principle: **ACP sits nearest the agent.** Control and pricing should see the agent's true intent — what it actually asked for — while routing, caching, and compression belong downstream, between ACP and the provider. A gateway upstream of ACP rewrites or caches requests before ACP sees them, which blinds both policy and pricing.

Honest current state:

- **Tested and supported today:** ACP's proxy forwards directly to the providers (Anthropic-native, OpenAI-compatible, and the OpenAI Responses passthrough). Your interception plane — hooks or decorators from the sections above — is unaffected by any gateway choice; it doesn't touch the model path.
- **Not supported today:** a per-workspace configurable upstream, so ACP can forward to *your* gateway (agent → ACP → LiteLLM/OpenRouter → provider). What we'd need to verify before claiming support for any specific gateway: that it passes real token-usage fields back through unchanged — a downstream layer that rewrites or caches without honest usage reporting would silently corrupt your cost data, and we'd rather say "untested" than guess.
- **Not supported:** putting your gateway between the agent and ACP. It works mechanically but breaks the principle above — ACP would meter post-rewrite traffic, not agent intent.

**Your coverage:** interception per your harness/framework section above, unchanged · proxy ✓ only in direct-to-provider mode, for now. If chaining ACP in front of your gateway is what's blocking you, [tell us which gateway](https://github.com/agentic-control-plane) — the per-gateway tests get prioritized by real demand.

## Check what you actually have

Two quick reads in [the console](https://cloud.agenticcontrolplane.com):

- **Interception live?** [Logs](https://cloud.agenticcontrolplane.com/logs) shows tool calls within seconds of your agent's next action.
- **Proxy live?** Any run showing a dollar cost was metered; a run with tool calls but no cost means model calls are bypassing the proxy.

A `coverage` doctor command and a per-agent Coverage card in the console — reporting interception / proxy per agent in exactly this shape — are in progress under the same effort as this page.