Toju/docs-site/docs/desktop-and-local-api.md

sidebar_position

sidebar_position
3

Desktop and Local API

Electron Hosting Model

The desktop app hosts local documentation through the existing Electron Local API server. This server is implemented with Node's http module in the Electron main process and uses async request handlers for routing, file reads, and streamed responses.

The endpoint is manually activated. Opening the Docusaurus docs from the desktop title bar enables the local server and docs endpoint if necessary, then opens the system browser to the generated static site.

This avoids:

• starting a Docusaurus development server inside Electron;
• blocking the renderer thread;
• serving docs from a remote host;
• exposing the endpoint unless the user chooses to activate it.

Local Server Settings

Setting	Default	Meaning
enabled	false	Starts or stops the local HTTP server.
port	17878	Listening port.
exposeOnLan	false	Uses 127.0.0.1 by default; when true, binds to 0.0.0.0.
scalarEnabled	false	Enables /docs for the Scalar OpenAPI reference.
docusaurusEnabled	false	Enables /docusaurus for the built Docusaurus documentation.
allowedSignalingServers	[]	Server URLs allowed for Local API login.

Routes

Endpoint	Purpose	Auth
GET /api/health	Liveness, app version, timestamp, and LAN exposure status.	No
GET /api/openapi.json	OpenAPI 3.1 document for local automation clients.	No
GET /docs	Scalar API reference when Scalar docs are enabled.	No
GET /docusaurus	Docusaurus documentation entrypoint when Docusaurus docs are enabled.	No
GET /docusaurus/*	Static Docusaurus assets and pages.	No
POST /api/auth/login	Exchanges username, password, and allowed signaling server URL for a local bearer token.	No
POST /api/auth/logout	Revokes the current local bearer token.	Bearer
GET /api/profile	Reads the current local user profile.	Bearer
GET /api/rooms	Lists rooms known to this device.	Bearer
GET /api/rooms/{roomId}/messages	Reads local room messages with limit and offset.	Bearer

Authentication Flow

1. Add trusted signaling server URLs in desktop settings.
2. Start the Local API server.
3. Call POST /api/auth/login with username, password, and serverUrl.
4. MetoYou validates credentials through the signaling server.
5. The desktop app issues an opaque local bearer token.
6. Use Authorization: Bearer <token> for protected routes.

Bearer tokens are local to the running desktop app and are cleared when the Local API server stops.

Static Documentation Build

Docusaurus is a static site generator. The repo builds docs-site/ into docs-site/build/, and Electron serves those files from the local API server.

Development commands:

cd docs-site
npm install
npm run start

Build command:

npm run build:docs

Packaged desktop builds include the generated static output as an Electron extra resource.