Skip to main content
The Meradomo agent exposes a localhost-only HTTP management API on 127.0.0.1:8765. Any process on the same machine can call the open tier (publish). The owner tier (approve / revoke) is handled by the menu-bar app, not by your app.

​
Publish lifecycle

App names must match ^[a-z0-9-]{1,63}$ and must not be reserved (www, portal, or the customer’s own name).

​
Open tier — any local process

​
POST /publish

Request a publication.
Then poll GET /publish/:name until status === "live".

​
GET /publish/:name

Returns 404 if the name was never published or was fully revoked.

​
DELETE /publish/:name

App-initiated stop. Removes the live route but keeps the approval, so a later POST /publish is immediately live without another prompt.

​
GET /status

The agent’s connection state and a summary of published apps.
Use this on startup to detect whether Meradomo is installed — if the call fails, run standalone and hide any “available through Meradomo” UI.

​
Identity headers — the X-Meradomo-* contract

On every proxied request to your app, the agent:
  1. Strips all inbound X-Meradomo-* and X-Forwarded-* headers.
  2. Injects verified, non-spoofable values:
Treat these as the sole source of identity — no sign-in logic needed. See Security model for the unspoofability guarantee.
X-Meradomo-Role is the only way to tell the owner from somebody they shared with. Every visitor arrives from 127.0.0.1, because that is what a proxy in front looks like — so deciding it from the connection address hands your owner’s controls to everybody.
Key per-person data on X-Meradomo-User, not on the email: it is stable, and it lets somebody change address without losing what they had.

​
Owner tier (informational — the menu-bar app)

Approving, denying, and revoking apps is the menu-bar app’s job (guarded by a secret only it knows). Your app never calls these routes; it just handles the pending → live transition by polling GET /publish/:name.

​
Sharing your app with other people

An app that bundles the engine can also invite people to it, so its owner never leaves your app to share it. That needs a capability the engine hands out at registration — see Sharing your app with other people. An app taking the detect-the-app path (this guide) cannot: it has no engine of its own, and the running Meradomo app’s credential is not yours to borrow. Your owner shares from the menu bar or the account page instead, and your app still receives the resulting visitors with full identity headers as above.

​
Local development notes

  • The management API binds 127.0.0.1 on a real Mac. Never expose port 8765 to the network.
  • No authentication is required for open-tier calls — any local process can publish.
  • Bind your own server to 127.0.0.1 too, so nothing on the network reaches it un-fronted by Meradomo.