Local status API

  • Desktop app
  • All plans
View as Markdown

What it does

A read-only HTTP endpoint on your own computer that your tools (a status bar, a terminal dashboard, a script) use to read the live status of your agents and the backlog of your projects, without spawning AgentsRoom's internal MCP server. Its address and a token are published in a file at a fixed path, ~/.agentsroom/local-api.json, so a client never depends on where the app is installed (an AppImage mount changes on every launch). Responses are versioned JSON under /v1/: within v1, fields and values are only ever added.

Where to find it

Desktop: Settings > Dev tools > Local status API. Off by default. Once on, the row shows the listening address and the path of the discovery file. API reference opens this page.

How to use it

  1. Turn on Local status API.
  2. Read ~/.agentsroom/local-api.json (Windows: %USERPROFILE%\.agentsroom\local-api.json). It holds apiVersion, url (http://127.0.0.1:<port>), port, token, pid and updatedAt.
  3. Call an endpoint with the token:
f=~/.agentsroom/local-api.json
curl -s -H "Authorization: Bearer $(jq -r .token "$f")" "$(jq -r .url "$f")/v1/agents?project=$PWD"

Endpoints, all GET:

  • /v1: API version and app version, a health check.
  • /v1/projects: the projects open in AgentsRoom (id, name, path) with agentStatusCounts, for example { "busy": 2, "waiting_input": 1 }.
  • /v1/agents?project=<path or id>: every agent of the project (the agent a trigger starts for one run only while its console is open, as in agents_list_live), with id, name, role, temporary, status, provider, model, sessionTitle, lastActivity, backlogTaskId, workPhase, blockedReason, startedAt, updatedAt.
  • /v1/backlog?project=<path or id>&status=todo,in_progress&limit=200: tickets in board order, with id, title, status, type, tags, agentId, agentName, teamId, position, createdAt, updatedAt, completedAt; plus total, count, fetchedAt and stale. limit goes up to 1000, 200 by default.

project takes the project folder (any sub-folder works, so $PWD from inside a repository is enough) or the id listed by /v1/projects.

Agent status is one of offline, starting, idle, busy, waiting_input, blocked, rate_limited, degraded, failed. Ticket status is one of todo, in_progress, pending, in_review, done. Treat a value you do not know as "unknown": new ones can appear within v1.

Errors are JSON too: { "apiVersion": 1, "error": { "code": "...", "message": "..." } }. Codes: unauthorized (401), forbidden (403), not_found (404), method_not_allowed (405), invalid_parameter and project_required (400), project_not_found (404), project_ambiguous (409: several open checkouts share that id, ask by path), backlog_unavailable (502), not_signed_in (503), internal_error (500).

Settings

  • localStatusApiEnabled (global, Settings > Dev tools > Local status API): starts the listener. Default off. Machine-local, never synced with the account: it opens a port on this computer only.

Agent tools (MCP)

None of its own. An agent can switch it with settings_set on localStatusApiEnabled, when the user asks for it. Inside AgentsRoom, agents keep reading the same data with agents_list_live and backlog_list.

Providers

All providers, no difference: the status comes from each agent's console, whatever its CLI.

Mobile

Not on the mobile app: the endpoint serves programs running on the computer next to AgentsRoom. The phone already shows the same agent status and backlog in the app itself.

Limits

  • Loopback only (127.0.0.1): never reachable from another machine. A request from a web page (it carries an Origin header) or naming another Host is refused.
  • The port and the token change every time the listener starts (app launch, switch turned on). On a 401 or a refused connection, read the file again. No file means the app is closed or the API is off.
  • Agent data is at most about one second old. The backlog comes from your account through the app's own session: cached 15 seconds, served from the last good copy with stale: true when agentsroom.dev cannot be reached, and it needs the app to be signed in.
  • Read-only by design: nothing can be started, changed or sent through it.
  • The file follows the app data folder: AGENTSROOM_DATA_DIR moves it, development builds use ~/.agentsroom-dev/.

Common questions

  • Can my status bar show which agents are waiting for me? Yes: poll /v1/projects and read agentStatusCounts.waiting_input, or /v1/agents for their names.
  • Why not run the MCP server myself? Its path and its payloads are internal and change between releases. This endpoint is the supported, versioned contract.
  • Does it work while AgentsRoom is closed? No. It serves the app's live state, and the file is removed when the app quits.
  • Can other accounts on the computer read my backlog? No. The token sits in a file only your user account can read, and the listener answers nothing without it.
  • Are the ids the same as the ones agents see? Yes: agent ids match agents_list_live, ticket ids match backlog_list.

Related