Web chat and HTTP API

The HTTP server presents two faces of the same system: web chat for people and an API for authorised clients. Both pass through the same identity, ownership, and capacity controls. Knowing a URL or identifier does not grant access to another user's data.

Opening Metnos in a browser

The default web-chat port is 8770. On the computer hosting Metnos, open:

http://127.0.0.1:8770/

If you allowed local-network access during installation, you can use the server's private address from a phone or another computer on the same network. For example:

http://192.168.1.33:8770/

The address is only an example. At the end of installation, Metnos prints the addresses it actually detected and stores the base URLs in ~/.local/share/metnos/install_summary.md. The user page is /admin/users; /amin/users contains a typo and correctly returns 404.

During installation phase 4, you can restrict the interface to a browser running on the server itself. Metnos then listens only on 127.0.0.1, and LAN URLs do not work. The interactive installer offers LAN access by default; starting the HTTP process by itself takes the more conservative local-only default unless explicitly configured.

First and later access

At the end of installation, Metnos also prints one or more complete administrator links. Each contains a single-use code valid for 15 minutes. Opening one establishes the browser's administrator session and takes you to Settings. These complete links are not stored in the installation summary; that file keeps only the base URLs.

If the link has expired or has already been used, open /admin/login and enter the administrator key created during installation. Do not share either the one-time link or the key.

A browser paired with an ordinary user receives a separate cookie. It can use chat and the surfaces admitted for that role, but it does not become an administrator. To create users and pair browsers, see Pairing and identity.

What the server contains

Metnos builds one aiohttp application and connects four groups of functions to it:

A request body may be up to 50 MiB to accommodate reference images. Turns that run Python work pass through a bounded worker pool with a global queue and a per-caller limit. When capacity is unavailable, the server reports that fact and tells the caller when to retry.

Two services remain separate. The remote-executor protocol normally uses 127.0.0.1:8765; the browser-control component normally uses 127.0.0.1:8771. These are not alternative chat ports and should not be exposed as user interfaces.

Main route families

The route registries in code remain authoritative. This table explains the shape without promising an immutable endpoint list.

Identity and authorisation

Before calling a function, the server classifies the request as anonymous, user, or admin.

• The administrator key presented as a Bearer token, or a valid administrator cookie, identifies the administrator.
• A registered device token or paired-browser cookie identifies a user. The pairing registry is checked on every access, so revocation also invalidates an old cookie.
• The anonymous role can use only explicitly public routes, including the liveness probe, static assets, and valid single-use links.
• Anonymous LAN access as a user is an optional compatibility mode and is disabled by default. Even when enabled, it receives an empty synthetic scope until the browser is paired.

An invalid Bearer token never falls through to optional LAN trust. Proxy headers are considered only when the TCP connection comes from an explicitly trusted proxy; a client cannot make itself local by writing X-Forwarded-For.

The administrator cookie lasts up to seven days and the user cookie up to ninety. Both are HttpOnly. The Secure option is applied when the browser reaches Metnos over HTTPS; the administrator uses the stricter SameSite policy.

Direct and resumable turns

Direct turn

POST /agent/turn accepts JSON or multipart data containing text and images. It can return one JSON document or send SSE events as the turn progresses. If the connection breaks, this route alone does not provide the same reconnection behaviour as the decoupled path.

Resumable turn

POST /agent/turn/submit reserves capacity and returns 202 with a turn_id. Work continues if the page is refreshed. The browser can reconnect to the stream, resume after the last event it saw, or poll persisted status.

Stream, status, history, gallery, feedback, and retry always check ownership. Guessing a turn_id does not allow somebody to read or repeat another user's turn.

One chat across several devices

Only one browser may write for each user-and-web-channel pair at a time. If a second browser opens the same chat, Metnos can cancel, make the new session active, or continue the previous conversation on the new device. Transfer atomically revokes the old browser's write access.

The conversation belongs to the user, not the device. This prevents a phone and laptop from creating two concurrent branches while pretending to be the same session. Details are in Pairing and identity.

Network boundaries

• The server does not terminate TLS. A normal installation uses HTTP on the private network. Do not forward port 8770 from the router or expose it directly to the Internet.
• LAN does not mean Internet. Default local networks include loopback, 10.0.0.0/8, 172.16.0.0/12, and 192.168.0.0/16. The list is configurable and does not grant an identity by itself.
• An HTTPS proxy needs configuration. Only trusted proxies may tell Metnos the original address and scheme.
• There is no general per-IP rate limiter. If Metnos sits behind a proxy, that proxy must add protections appropriate to its exposure.
• One instance per state store. A process lock prevents two servers from using the same installation at once.

Checking the service

curl -fsS http://127.0.0.1:8770/agent/health
curl -fsS http://127.0.0.1:8770/.well-known/metnos.json
curl -fsS -H "Authorization: Bearer <administrator-key>" \
  http://127.0.0.1:8770/agent/stack/health

The first request proves only that the process responds. The last one is administrator-only and also checks the catalog and browser-service contract, making it the more useful probe before a full test.

For message transport, continue with Conversation channels. For who may enter and under which identity, see Pairing and identity.