Connect ACP Agents

Use the open-source @agentrq/acp-gateway to connect Gemini CLI and other ACP-compatible agents to AgentRQ.

While Claude Code is natively supported, many other agents now support the Agent Client Protocol (ACP). AgentRQ provides an open-source bridge (ACP Gateway) that allows these agents to use AgentRQ workspaces for human-in-the-loop task management.

How it works

ACP Agent (e.g. Gemini)

ACP Gateway

AgentRQ MCP Server

1 Find Your Agent

There is nothing to install. Every example here runs the Gateway through npx @agentrq/acp-gateway@latest, which fetches the current release each time — so you are never driving a version you installed months ago and forgot about.

# See which agents the ACP registry publishes
npx @agentrq/acp-gateway@latest --list-agents

--list-agents prints every agent in the ACP registry alongside how each one can run on this machine. The name in the first column is the registry id you pass to --agent everywhere below.

2 Configure .mcp.json

The Gateway reads your workspace configuration from .mcp.json. Place this file in your project root or any parent directory.

.mcp.json

{
  "mcpServers": {
    "agentrq": {
      "type": "http",
      "url": "https://WORKSPACE_ID.mcp.agentrq.com/mcp?token=TOKEN"
    }
  }
}

3 Start Your Agent

Run everything below from your workspace root — the directory holding .mcp.json. Log in once, then start the agent and leave it running; it picks up tasks as you assign them.

Log In, Once

$ npx @agentrq/acp-gateway@latest --login --agent codex-acp

The first run also downloads the agent, so there is nothing to install by hand. Credentials stay with the agent — the Gateway never stores them.

Start The Agent

$ npx @agentrq/acp-gateway@latest --agent codex-acp

Add --max-concurrency 1 to keep the agent on one task at a time; it defaults to 1 and accepts more.

Agents Without A Checksum

$ npx @agentrq/acp-gateway@latest --login --agent antigravity-acp --allow-unverified-agent

Registry binaries are checked against a published sha256 before they run, and roughly half of them publish none. Rather than run something it cannot vouch for, the Gateway refuses and asks you to opt in explicitly. The flag is only needed while the binary is being installed — downloads are cached per agent, version and platform, so the runs after it can leave the flag off.

Choosing A Model

$ npx @agentrq/acp-gateway@latest --list-models --agent antigravity-acp --allow-unverified-agent
$ npx @agentrq/acp-gateway@latest --model gemini-3.8-flash-high --agent antigravity-acp
$ npx @agentrq/acp-gateway@latest --agent antigravity-acp

Ask the agent what it supports, start it on one of those models, or omit --model and take the agent's default.

Not sure which registry id your agent uses? See the ACP Agents Directory for Gemini CLI, Codex, Cursor, Cline, Hermes Agent, OpenClaw, and 50+ other ACP-compatible agents.

4 What the Gateway Bridges

Task Notifications

Forwarded from AgentRQ to your agent as ACP prompts.

Permission Requests

ACP agent requests permission → Gateway proxies to AgentRQ → verdict returned.

File Operations

Agents can read and write files relative to the current directory.

Tool Dispatch

Proxies ACP tool calls directly to AgentRQ MCP server tools.

Open Source Gateway

The ACP Gateway is open-source and community-driven. You can inspect the code, contribute fixes, or build your own specialized bridge.

View on GitHub

Setup Complete?

Learn how to manage your workspace next.