built 15 min verified 2f6dc6b (2026-09-24)

Mini-apps

A mini-app is a published web service that hello.mesh shows as a card on the Apps shelf, not only as a line in Services. Visitors tap Open here (embed) or Open (new tab). The app can ask hello.mesh who the visitor is without ever seeing the private key.

Status: built in current hello.mesh (AppsPanel, GET /api/apps, identity bridge). Older nodes have no Apps section — the marker is still valid on the wire. Trusted HTTPS names (no certificate warning) are not part of this page.

What visitors see

Do: open http://hello.mesh as a person on the mesh.

Expect: Apps · tap to open, a count, then cards. Mini-apps do not also appear under Services. Empty copy: "No apps on this mesh yet."

If not: see Find services and Troubleshooting.

Mark a service as an app

Do: when you publish, include:

mjolnir-meshd publish keyed --port 3000 --txt proto=http --txt app=v1 --txt path=/

path is optional (default /). It must start with / and stay on that origin. Non-http/https protocols are never mini-apps, even with app=v1.

Expect: the directory record carries app=v1. After hello refreshes (a few seconds), the name leaves Services and appears under Apps.

Serve a manifest

hello.mesh does not fetch this from the visitor's browser. The router GETs /.well-known/mesh-app.json on the service's own IP and port (only 10.42.0.0/16 or 10.254.0.0/16), then serves the result at GET /api/apps.

Do: serve JSON like:

{
  "v": 1,
  "name": "Keyed",
  "description": "Tasks for the house",
  "icon": "/icon.png",
  "embed": "card",
  "height": 480
}
Field Rule
v Must be 1
name ≤ 40 chars
description ≤ 140 chars
icon Same-origin path; node inlines a small png/jpeg/webp/svg
embed card or link (default link)
height CSS px, clamped 120–640

Expect: the card shows name, description, icon. embed: card plus a .mesh name (not a raw IP) gets Open here. Raw IPs always link out.

If not: missing or failed manifests still list the mini-app, just undecorated. Timeouts are 3 seconds; the node retries at most every 5 minutes.

Identity from a card

Do: from the embedded card, ask hello.mesh over postMessage (mesh: mini-app/v1, type: identity.request, a nonce, one MessagePort).

Expect: hello.mesh shows consent outside the iframe (same facts as /assert). On approve, the token comes back only on that port. The card may show "Identity shared with …".

If not: no identity yet — the visitor uses Create your identity. Link-out tiles use the full-page sign-in flow instead.

App-supplied code never runs on the hello.mesh origin. The iframe is sandboxed and loaded only after a tap.

Living spec: `openspec/specs/mesh-mini-apps/spec.md`.

Next: Contribute.

Next: Contribute →