Skip to content
Agentic Control Plane

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:

Note to AI agents: this page is also served as raw markdown at /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: 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:

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.

I use Codex

The same installer detects Codex:

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 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:

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. 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.

I run a Hermes agent

Four commands, native to Python:

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 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.

I use the DeepSeek Harness

Two commands, native to dsh’s plugin system:

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 does this for every existing profile automatically).

dsh needs Node 22, and it’s a developer preview — the integration guide 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.

I built with LangGraph or CrewAI

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

pip install acp-langchain   # or acp-crewai

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

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 StateGraphs: 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:

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:

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 · Deep Agents · CrewAI · all 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):

  • 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 — the per-gateway tests get prioritized by real demand.

Check what you actually have

Two quick reads in the console:

  • Interception live? 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.