Join the waitlist

Publishing a mini-app#

Publishing does three things: it names your app, gives you the secret you verify launch tokens with, and (optionally) hosts it for you.

App IDs — owner/slug#

Every app has an id of the form owner/slug:

  • owner is your account username (a namespace account may carry one :, e.g. acme:team).
  • slug matches ^[a-z][a-z0-9-]*$.
  • Each half is at most 64 characters.
✓  ada/todo        ✓  acme:team/notes
✗  com.ada.todo    ✗  noslash        ✗  /leading

You may only publish under a namespace you own.

Register#

Registering mints (on first call) the signing secret for your launch tokens.

mafold apps register you/todo \
  --url https://todo.example.com \
  --name "Todo" \
  --capabilities room,chat.send,storage

The result includes your secret:

{ "id": "you/todo", "url": "https://todo.example.com", "secret": "…" }

The secret is shown once

The signing secret is returned only on first registration. Store it in your backend's secrets manager immediately. Re-registering the same app (to update the URL, name, or capabilities) keeps the existing secret and returns null for it.

--capabilities is the list your app is allowed to use at runtime — declare only what you need (room, storage, chat.read, chat.send, ui.*; see the SDK reference).

Your app secret#

The secret signs every launch token, and your backend verifies with it — see Authentication. If it leaks, rotate it (the old one stops verifying immediately):

mafold apps rotate-secret you/todo

Hosting#

You can host the app anywhere — any HTTPS URL works. Mafold also offers free static hosting on *.mafold.app so you don't need your own server for a front-end-only app.

mafold apps deploy --dir ./dist --name todo
# → https://todo-3f2a.mafold.app

Deploying uploads your built files and serves them at <name>-<id>.mafold.app. Redeploying the same site replaces it wholesale (files not in the new upload are removed). Current limits per site: 200 files, 5 MB per file, and a small per-account site cap.

Front-end plus a backend

Static hosting serves your front-end. Launch-token verification still needs a backend that holds your secret — host that wherever you like and point your app at it.

Registry rules#

  • Identity = Mafold identity. If your app identifies users, Mafold.auth() / initData verification is the only permitted way — no own signup forms, no third-party login (Google, email links, …) inside the app. Users are already signed in; use that. Apps that don't need identity at all are welcome. See Authentication.
  • Declare only the capabilities you use; undeclared capabilities reject at runtime.
  • Your app secret stays on your backend — never ship it to the browser.

Putting it together#

  1. Build your front-end and add the SDK.
  2. mafold apps register you/todo --url … --capabilities … → save the secret.
  3. Verify initData on your backend with the secret (Authentication).
  4. Host the front-end (your own, or mafold apps deploy).
  5. Open it from a conversation — Mafold hands your page a verified identity and a shared room, and you're multiplayer.