# Local status API > 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. - Area: Desktop app - Plans: All plans - Last checked against the product: 2026-10-16 - Web page: https://agentsroom.dev/docs/local-status-api ## 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`, `token`, `pid` and `updatedAt`. 3. Call an endpoint with the token: ```sh 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=`: 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=&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 - [Agent Status Tracking](https://agentsroom.dev/docs/agent-status-tracking.md): what each agent status means in the app. - [Backlog Task Board](https://agentsroom.dev/docs/backlog-task-board.md): the board the tickets come from. - [AgentsRoom MCP](https://agentsroom.dev/docs/agentsroom-mcp.md): the tools agents use inside AgentsRoom.