Local API

TALOS Desktop is two parts: the window, and a local server it talks to over HTTP. Everything the window does — sessions, files, Git, models, the browser — goes through this API. It is described here for transparency, to build on the server when you run it from the source, and to read what a session streams.

Base

http://127.0.0.1:<port>/api/v1

Operations

268116 GET136 POST7 PATCH9 DELETE

Answers

JSON envelope talos.harness-ui.api.v1; 3 event streams

Access

loopback only; the talos_token cookie when a token is set

Errors

272 codes

Address

The server listens on the loopback address only (127.0.0.1 by default; ::1 and localhost are accepted), never on the network.

• In the app: the port is chosen for your profile at the first start and kept, so the window’s storage stays with it. It is not 4174.
• From the source (node harness-ui/server.mjs): http://127.0.0.1:4174/, or the next free port, printed at start; TALOS_HARNESS_UI_PORT requires an exact one. See Environment variables.

Every path starts with /api/v1. What is not under /api/ is the window itself (static files).

Access

When the server starts with a token (TALOS_HARNESS_UI_TOKEN, at least 32 characters), every /api/ request needs the talos_token cookie, or it answers 401 with AUTH_REQUIRED. Opening /?token=<token> sets the cookie (HttpOnly, SameSite=Strict) and redirects to /, so the token does not stay in the address bar. The app starts its server with a new random token every time and hands it only to its own window.

Three kinds of request carry more checks:

• Approvals and uploads (approving or revising a workflow, starting or controlling a run, deciding on a plan, uploading a file to the chat): the request must come from this TALOS window — its Origin must be the server’s own address, and Sec-Fetch-Site same-origin or none — or, from a program that is not a browser, from a server started with a token.
• Shutdown (POST /api/v1/admin/shutdown): from the loopback address only, with the shutdown token in x-talos-shutdown-token.
• Two paths without the cookie, each guarded by a narrower secret instead: the OpenRouter sign-in return (a one-time state of 32 random bytes, valid ten minutes) and the files of a rendered page (a 32-byte pass bound to a session and a folder).

Without a token (the server from the source, by default) the API answers whoever reaches the port on this computer; only the approvals above still refuse a program that is not a browser.

Answers

A JSON answer is an envelope:

{ "ok": true, "data": { … }, "meta": { "schema": "talos.harness-ui.api.v1", "generatedAt": "2026-09-30T12:00:00.000Z" } }

An error keeps the same shape with ok: false and an error:

{ "ok": false, "error": { "code": "NOT_FOUND", "message": "…", "title": "…", "explanation": "…", "action": "…", "doctorReference": "…" }, "meta": { … } }

code is stable and listed on Error codes with its HTTP status. message, title, explanation and action are the sentences the window shows (in Italian in this release). doctorReference opens the recorded detail: GET /api/v1/doctor/{reference}. An unknown failure is 500 INTERNAL_ERROR.

Any operation can answer these; each operation lists the others it can raise:

Code	Status	Meaning
AUTH_REQUIRED	401	This server accepts only the TALOS window that started it (or, for shutdown, the right token).
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
METHOD_NOT_ALLOWED	405	The address exists, but not with this method; the Allow header lists the methods it takes.
PAYLOAD_LIMIT	413	The body is larger than the server accepts: shorten it, or put the text in a file and attach it.
INTERNAL_ERROR	500	An unexpected error on the server; the Doctor has the detail, under the reference shown.

Some operations answer bytes (a file, an image) or an event stream instead; each operation says which.

Methods

• GET reads, POST acts, PATCH changes and DELETE removes.
• Every GET also answers HEAD.
• A path that exists with another method answers 405 with the real Allow header; a path that does not exist answers 404.
• Most operations refuse a query parameter or a body field they do not read (400, QUERY_INVALID) rather than ignore it.

Limits

Address of a request

4 KiB at most (path and query); longer answers 413.

Body

10 MiB by default (TALOS_HTTP_BODY_MAX_BYTES); larger answers 413 PAYLOAD_LIMIT. Operations with a fixed-shape body (a sign-in code, a batch) keep smaller limits.

Batch

250 items and 64 KiB at most in one batch delete.

Streams

a comment line every 15 s keeps a stream alive; a turn has no maximum duration.

Streams

A session streams its events as server-sent events: GET /api/v1/sessions/{sessionId}/events. Each event is a data: line of JSON with an id: (its sequence number); on reconnection the browser sends Last-Event-ID and the stream replays only what came after. A comment line every 15 s keeps the connection alive. The events are listed on Events.

A workflow run has its own stream, and the live browser its screen. Both are described with their operations.

Headers

Cache-Control

Nothing is kept in a cache. no-store

Content-Security-Policy

What the window may load and run. default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self'; frame-src 'self' http://localhost:* http://127.0.0.1:* https:; object-src 'none'; base-uri 'none'; frame-ancestors 'none'; form-action 'none'

Referrer-Policy

No address is sent onward. no-referrer

X-Content-Type-Options

The declared type is the only type. nosniff

X-Frame-Options

No other page may frame TALOS. DENY

Operations

• Sessions Start, list, fork, resume and configure sessions; their history, metrics and attachments. 23
• Turns and approvals Follow a session live, answer its approvals and questions, queue and redirect messages, run your own commands. 15
• Workflows Review, approve and start workflow proposals; follow and control their runs. 24
• Files and folders The session’s folder: browse, read, search, preview and change its files; choose folders for new sessions. 23
• Git and GitHub The Git state of a session’s folder and every Git action of the review panel; GitHub pull requests through gh. 39
• Library, notes, tasks, memory and research The project’s own records, the same the agent’s tools read and write. 31
• Tools and extensions The agent’s tools, and the hooks, MCP servers, plugins, skills and forged tools of a project, with their trust. 12
• Terminals The real terminals of a session. 3
• Models and providers The models on offer, provider keys and addresses, OpenRouter sign-in, and the web search source. 23
• Local models Models that run on this computer: the engine, installed models, Hugging Face downloads and what fits. 21
• Browser The built-in browser: reading pages, framing local previews, and the live browser the agent drives. 11
• Automations Task templates that run on a schedule. 12
• Health and diagnostics Whether the server is up, the Doctor’s readiness report, first-run state, and shutdown. 31
• Error codes Every code an operation can answer, with its HTTP status. 272

The same API as an OpenAPI 3.1 description, to import into an API client. It knows what this reference knows: paths, parameters, fields and their meaning, answers and error codes, not the types of fields.