Connect Codex Gateway

Use the open-source @agentrq/codex-gateway to connect Codex 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 (Codex Gateway) that allows these agents to use AgentRQ workspaces for human-in-the-loop task management.

How it works

Codex Agent (codex app-server)

ACP Gateway

AgentRQ MCP Server

1 Install Codex Gateway

The Codex Gateway is available via npm. You can run it directly using npx or install it globally.

# To install globally
npm install -g @agentrq/codex-gateway

# Or run directly via npx
npx @agentrq/codex-gateway -- [agent-command]

2 Configure Codex (.codex/config.toml)

Codex reads project-level MCP server config from .codex/config.toml. Create this file so the Codex agent can use agentrq tools directly during task execution.

mkdir -p .codex
cat >> .codex/config.toml << EOF
[mcp_servers.agentrq-workspace]
url = "https://WORKSPACE_ID.mcp.agentrq.com/?token=TOKEN"
EOF

3 Configure Gateway (.mcp.json)

Create a .mcp.json in your project root so codex-gateway can connect to the same agentrq workspace to receive tasks:

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

Note: .mcp.json is used by codex-gateway to receive tasks. .codex/config.toml is used by the Codex agent itself to call agentrq tools (e.g. reply, updateTaskStatus) during execution.

4 Start Your Agent

Run the gateway from your agentrq workspace root (the directory containing .mcp.json).

# Default: runs `codex app-server`
$ codex-gateway

# Custom codex command
$ codex-gateway -- codex app-server

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