AgentRQ: a self-hosted task board that AI agents read and write over MCP

The gap AgentRQ fills between a chat window and a task queue

A coding agent running in a terminal holds its plan in a context window. Close the laptop and the plan is gone. AgentRQ's answer is to move the plan into a database that both sides can reach: you through a web, desktop or mobile client, the agent through the Model Context Protocol. The README frames it as a shared workspace where humans and agents work together, and the mechanism behind that phrase is a task board plus an MCP server.

The intended user is someone running more than one agent, or one agent on more than one machine, who wants to see what is in flight without tailing logs. The README's own example is a task Claude creates appearing on your board instantly, so you can see what it is working on, what it needs, and what it just finished. That is a supervision problem, not an orchestration one. If your agents never need approval and never wait on you, the board adds a hop with no payoff.

Go backend, MCP server, SSE event bus: the actual data flow

The architecture section of the README splits the system into a Fiber REST API, an integrated mcp-go SSE server, a CoreMCP supervisor, a GORM data layer over SQLite, Google OAuth2 with JWT sessions, and an internal pub/sub event bus for real-time SSE notifications. The frontend is Vue 3 with Pinia and Tailwind, and it stays in sync with the backend over those SSE events rather than polling.

The part worth pausing on is CoreMCP. The README describes it as a global MCP server that lets agents manage all workspaces, tasks and statistics across the entire platform. That is a broader surface than the per-workspace MCP server, and it means an agent connected to CoreMCP is not scoped to one board. Whether that is a feature or a footgun depends on which agents you point at it.

On top of the MCP endpoints sits the ACP side. The repository ships an integrations directory and a plugins directory, and the Makefile exposes an acp-gateway target that runs @agentrq/acp-gateway against a named agent. The description says AgentRQ is designed to work with your own Claude subscriptions and any harness with ACP support, which is the real integration story: MCP for the task protocol, ACP for driving the agent process itself.

Events and workflows: signals instead of a YAML pipeline

Events are named strings such as qa_passed, deploy_finished or blog_published that a task fires when it completes. Wire an event to a workspace and that workspace receives a new task automatically. The README is explicit that this needs no polling and no glue code.

Workflows are the visual layer over the same primitive. A workflow is events and workspaces arranged on a graph; you drag a workspace onto an event to subscribe it, or an event onto a workspace to emit it on completion. The README contrasts this with a decision-tree DSL or YAML. That is a defensible choice for a release process with a handful of stages, and a poor one for anything with conditional branching, loops or fan-out, because a graph editor has no natural way to express those without turning into the DSL it was avoiding. The README does not document rollback or failure handling for a workflow node that never fires its event, which is the first thing to test before trusting a pipeline to it.

Installing AgentRQ with Docker Compose and creating a first task

The repository ships a docker-compose.yml that pulls agentrq/agentrq:latest and maps the port from a PORT variable, defaulting to 2026. Copy .env.example to .env first; the file itself says that for local development you typically only need the OAuth credentials, and that everything else has sensible defaults.

The compose file marks JWT secret, workspace token key, and the Google OAuth client ID and secret as required. Two more variables matter if you are not running on plain localhost: AGENTRQ_BASE_URL is the public URL of your instance, and AGENTRQ_DOMAIN is the same host without the protocol.

cp .env.example .env
# fill in AGENTRQ_AUTH_JWT_SECRET, AGENTRQ_AUTH_WORKSPACE_TOKEN_KEY,
# AGENTRQ_ACCOUNTS_OAUTH2_CLI_GOOGLE_CLIENT_ID,
# AGENTRQ_ACCOUNTS_OAUTH2_CLI_GOOGLE_CLIENT_SECRET
docker compose up -d

Storage defaults to SQLite with AGENTRQ_SQLITE_ENABLED=true and AGENTRQ_SQLITE_DSN=/storage/agentrq.db. If you would rather run PostgreSQL, the compose file has a second block of variables: set AGENTRQ_POSTGRES_ENABLED=true, fill in host, port, user, password and database name, and disable SQLite. The README does not document a migration path between the two, so pick one before you have data.

For development against source, the Makefile is the entry point. make dev runs the backend and frontend together, with the backend built from backend/cmd/server and the frontend dev server on port 5173.

make dev
# backend on :3000, frontend on :5173
make stop

Once the UI is up, the first real use is to create a workspace, create a task in it, and connect your agent. The README's description of the flow is that agents pull assigned tasks, update statuses, request permissions for sensitive actions, and communicate with you. To drive an agent through the gateway rather than only through the board, the Makefile shows the shape of the command:

npx @agentrq/acp-gateway@latest --model gemini-3.8-flash-high --agent antigravity-acp

Expect the task to appear on the board as a list or Kanban entry, and expect tool calls to land in the task detail view's History tab, which the README describes as a lane-grouped timeline split into Input, Agent and Tools, with each entry showing what ran, what it returned, and whether it was allowed or denied. That history is the fastest way to confirm the agent is actually talking to your instance.

Where AgentRQ is the wrong tool

The install is not a one-liner. Google OAuth2 is required rather than optional, so you need a Google Cloud project and a redirect URI that matches AGENTRQ_BASE_URL before the first login. There is a root login path, but AGENTRQ_AUTH_ROOT_LOGIN_ENABLED defaults to false, so it is off unless you turn it on. If you wanted to run this on an air-gapped network with local accounts only, the compose file gives you no path to that.

SQLite is the default store and the Dockerfile builds with CGO_ENABLED=0 against a pure Go SQLite driver. That keeps the image simple, and it also means the database is a single file at /storage/agentrq.db. Concurrent writers across many agents are where that choice starts to hurt; the compose file's PostgreSQL block exists for exactly that reason, and switching later is not documented.

The desktop app is Electron and renders the same Vue components as the browser, so it is not a separate implementation to keep in sync. But the README's desktop section is truncated in the repository's own front page, and the Makefile's desktop target builds installers into desktop/release and, in its own words, publishes nothing. Treat desktop as a build-it-yourself path rather than a download.

Finally, the whole premise is human-in-the-loop. If your workload is a batch of independent jobs with no approval step, the board, the SSE bus and the OAuth layer are overhead you will pay for and never use.

How AgentRQ differs from running agents inside a single harness

The closest alternative is not another task manager, it is the agent's own session state. Claude Code and similar harnesses keep a plan in the conversation and a todo list in the process. That works for one agent on one machine and costs nothing to set up.

The difference in approach is where the state lives. In a harness-native todo list, the agent owns the plan and you observe it by reading the transcript. In AgentRQ, the plan is rows in SQLite behind a REST API, and the agent is one of several clients of that API. That inversion is what makes multiple agents and multiple devices possible, and it is also what makes the system fail differently: if the AgentRQ server is down, the agent's view of its own tasks is down with it, whereas a local todo list keeps working offline.

A second alternative is a plain job queue with a web UI. Those are simpler to operate and usually have mature retry semantics, which the README does not describe for AgentRQ tasks. What they lack is the MCP endpoint and the permission-request flow, which is the reason to pick AgentRQ in the first place. If you do not need an agent to ask before acting, a queue is the better fit.

Licence, maintenance and what an upgrade costs

AgentRQ is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant. The practical consequence for a self-hosted deployment is that nothing in the licence stops you from forking the backend or shipping the desktop build internally. It does not remove the obligations: keep the licence and notice files with any redistribution, and note that Apache-2.0 does not grant trademark rights, so the AgentRQ name and logo are a separate question from the code. This is a description of the licence text, not legal advice.

The repository is not archived, and the last push was on 2026-09-10. Releases are frequent and small: v0.5.21 on 2026-09-10, v0.5.20 on 2026-09-09, v0.5.19 on 2026-09-09. A patch cadence that tight in a single day suggests active work, and it also means the version number is a weak signal of stability. The compose file pins agentrq/agentrq:latest rather than a tag, so a restart can move you across releases without warning. If you are running this for a team, pin a digest.

Upgrade cost is dominated by the database, not the binaries. The image is built from scratch with a static Go binary and a prebuilt frontend, so replacing it is cheap. Schema changes across a 0.5.x line are the thing to watch, and the README does not document a migration or rollback procedure. Back up /storage/agentrq.db before pulling a new image.

Editorial conclusion

Adopt AgentRQ if you already run Claude Code or another ACP-capable harness and want one board where several agents pull tasks, fire events and ask you before touching anything sensitive, and you are willing to terminate TLS and provision Google OAuth yourself. Skip it if you want a hosted service, or if your agents never need a human in the loop: a plain queue or a chat session is cheaper. Before committing, verify three things on your own instance: that the workspace token flow survives your reverse proxy, that AGENTRQ_SQLITE_DSN points at a volume you actually back up, and that your harness connects through the ACP gateway rather than only the web UI.

Frequently asked questions

Official sources

1. agentrq/agentrq on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases