Toju/agents-docs/features/desktop-local-api.md

Desktop Local API

Status: Active Last updated: 2026-07-05

Overview

Electron hosts an optional localhost HTTP API that exposes read-only access to the local SQLite database, proxies login to allowed signaling servers, and serves bundled Docusaurus documentation offline.

Responsibilities

Layer	Owns
Electron api/router.ts	HTTP routes, bearer token store, CQRS query dispatch
Desktop settings	Enable/disable Local API, port, allowed signal servers
docs-site build	Static bundle mounted at /docusaurus/*

Trust boundary

Separate in-memory bearer tokens from signaling-server session tokens. Login via Local API issues a local token; read routes require Authorization: Bearer. See authentication.md.

Routes (summary)

Method	Path	Auth	Purpose
GET	/api/health	No	Local API liveness
GET	/api/openapi.json, /docs, /scalar/api-reference.js	No	API docs (Scalar)
GET	/docusaurus/*	No	In-app documentation site
POST	/api/auth/login	No	Proxy to configured signaling server; returns local bearer
POST	/api/auth/logout	Bearer	Revoke local token
GET	/api/profile	Bearer	Current user profile
GET	/api/rooms, /api/rooms/{roomId}, .../users, .../messages, .../bans	Bearer	Read-only room data
GET	/api/messages/{messageId}, .../reactions, .../attachments	Bearer	Message graph
GET	/api/users/{userId}, /api/attachments, /api/plugin-data	Bearer	User + plugin data reads
GET	/api/meta/{key}	Bearer	Meta key lookup

Database routes return 503 when SQLite is not initialised.

IPC

• get-local-api-status, open-local-api-docs, open-docusaurus-docs

Related

• authentication.md — trust table
• electron/CONTEXT.md — Local API vocabulary
• docs-site/CONTEXT.md — documentation bundle

Changelog

Date	Change
2026-07-05	Initial Local API route catalog