Skip to content

🤖 Open-source, local-first alternative to Grok Bot, OpenAI dots and Claude Duet. Your own AI bots on any model: GPT, Claude, Gemini, Grok, DeepSeek, Kimi, GLM and 70+ more through one Modelflare key. Reach them in the app, WeChat or Feishu; they remember you, work in the background, run commands and use your computer. Pay per use.

18.5 KB
Raw Blame

Catalog bot framework

简体中文

A bot is a folder. The app contains no code for any single bot, so shipping a new bot needs no app release. Whoever builds it, and however many there are, every bot passes the same checks, so consistency and safety come from the framework.

While the catalog is empty, existing users see no change: no new sidebar entries, and the same onboarding.

Getting started

You need Node.js 22.13+:

git clone [email protected]:modelflare-ai/AnyModelBot.git
cd AnyModelBot
npm install
npm run bot -- new <id>            # scaffold bots/<id>/ from the template
npm run bot -- check bots/<id>     # static checks; fails until every TODO is filled in

Once check passes, ask someone to judge whether it's worth shipping, then commit directly to master. There's no need for a PR.

Architecture

Authors (people / Claude + the dev skill / a pipeline later)
        │
        â–¼
Bot package: bots/<id>/ ──► checks ──► human look ──► pack and sign ──► catalog URL
                                                                          │
                                                                          â–¼
App: catalog sync · runtime (sandboxed iframe, bridge, state files) · UI kit · bot process
Part Where What it does
Format src/botkit/format.ts, schema.ts bot.json, permissions, limits, the JSON Schema subset
Checks src/botkit/check.ts, render.ts, evals.ts Static rules, rendering, real-model evals
Publishing src/botkit/bundle.ts, pack.ts, sign.ts Content-addressed bundles, signed catalog, takedowns
Sync src/botkit/catalog.ts, config.ts Fetch, verify, cache, download on demand
Instances src/botkit/installer.ts, app-skill.ts Install on first use, update, take down, remove
Server src/web/botapp.ts Static routes with CSP, catalog and instance APIs
UI kit ui/botkit/ The only thing a bot's UI may import
Container ui/screens/bot-app.js, discover.js, ui/lib/bot-bridge.js iframe, bridge, composer, Discover page
Permissions src/agent/host.ts, dsh-runtime/plugins/amb-bot-gate.mjs Undeclared permissions are refused at runtime
Tooling src/cli/amb-bot.ts, assets/bot-template/ The amb-bot command and the template

Bot package

bots/<id>/
  bot.json           Metadata: name, summary, avatar, permissions, starters, imported skills, version
  persona.md         Persona and system prompt
  skills/            Skills. Imported skills live here too and ship with the catalog
  ui/                The UI: index.html, static files, locales/
  state.schema.json  The data contract between the UI and the bot
  sample.<lang>.json Sample data shown on open, in the user's language. zh-CN and en are required; other languages fall back to en
  evals/             tasks.json (eval tasks), injection.json (prompt injection cases)

bot.json

Field Notes
id Lowercase letters, digits and hyphens, 2–48 characters
version, minAppVersion Bot version; users on an older app don't see the bot
name, summary Name (≤ 24 characters), one line (≤ 80 characters)
about 1–3 lines shown in the info panel
starters 2–3 clickable sentences; each must visibly change the view
avatar A base character (blue, yellow, green, red, purple, orange) or a field expert (law, health, finance, code, design, writing, education, science, data, marketing, cooking, translate). It only sets the look. Older apps don't know the experts, so set minAppVersion to the release that added them
permissions See below
skills Imported skills: name, source, sha256 (from amb-bot hash), author, license, url. Your own skills aren't listed

Text fields are { "zh-CN": …, "en": … }, both required. The framework requires these two; ja, ko and ru fall back to en. Bots listed in this repository need all five languages, including text, UI and sample data, and test/bot-catalog-site.unit.test.ts checks this.

Permissions

Permission Allows When not declared
workspace-write Writing its own workspace. Required, because the bot writes app/state.json Read-only preset
network Web search, fetching pages, network from commands. Asks the user on first use Tools refused; commands have no network on Linux; scripts that use the network fail static checks
channel-send Background tasks, whose results are sent to chat channels. Asks the user on first use task_start and task_message refused
computer-use Controlling the computer Not loaded
accounts Connected accounts (Notion, Feishu data) Not loaded

On macOS and Windows, network access from commands is covered by the static scan; at runtime only tool calls are blocked.

UI

The UI runs in an iframe with sandbox="allow-scripts allow-forms", so it has an opaque origin: no network (connect-src 'none'), no cookies, no access to the app's APIs. All data goes through the bridge and the parent page.

It may only reference the UI kit and files in its own folder:

<link rel="stylesheet" href="/amb/botapp/kit/kit.css" />
<script type="module" src="./app.js"></script>
import { html, mount, useBot, Page, Card } from "/amb/botapp/kit/kit.js";

function App() {
  const bot = useBot();
  if (!bot.ready) return null;
  return html`<${Page} title=${bot.state?.title}>…<//>`;
}
mount(App);

useBot()

Field Notes
ready The bridge is ready
state Contents of app/state.json, with invalid parts removed; updates when the bot changes the file
issues What didn't match the contract, for debugging
sample Still showing sample data (no instance yet)
busy The bot is replying
lang, t(key, params) Current language and text from ui/locales/<lang>.json
send(text, action) Send a message as the user. action is a UI action; the bot receives [ui-action] {…}
stop() Stop the current turn
pickFile({ accept, multiple }) Let the user pick files into app/inbox/; returns [{ name, size, path }]
readFile(path) Read other text files under app/ (up to 2 MB)
readImage(path) Read an image under app/ (png, jpg, gif, webp, svg, up to 16 MB). Returns { url } for an <img>. Needs an instance; images for sample data live under ui/ and use relative paths
openFile(path, { reveal }) Open a file under app/. Call it from a user click. The desktop app opens it with the system app or shows it in its folder (anything that would run on opening is only shown in its folder). On the web it downloads
desktop This is the desktop app, so files can open with the system app
openUrl(url) Open an external page once the user confirms the address; http(s) only

The kit follows the app's theme, language, text size and motion preference on its own.

Components

Page, Section, Card (on adds the highlight background), Row, Stack, Grid, Button, Field, Notice, Empty, Meter, Table, Link (an external link the user confirms before it opens). Design system classes (.btn, .field, .t-title…) and tokens (--fg, --well, --space-*, --fs-*) work directly; see ui/design/README.md. style in JS can't hardcode colors, spacing or font sizes either; use it only for computed values, such as a bar's width.

Add components to ui/botkit/kit.js as real bots need them, rather than working around the kit in one bot. The kit ships with the app, so adding to it needs a release. Register new abilities in KIT_SINCE in src/botkit/format.ts: a bot using one can't have a lower minAppVersion, and the check enforces it (ui.min-app-version).

Bridge

ui/lib/bot-bridge.js checks event.source and only exposes an allowlist. Approval APIs are never exposed.

Method Purpose
init Language, theme, text size, motion, text and basic bot info
readFile, readImage Read-only access to app/ in the workspace, with no way out
openFile Open or download a file under app/. Runs only if the parent page confirms the user just clicked
send, stop Send a message, stop
subscribe Receive turn, file and env events
pickFile Pick files
openChannels Open connection settings so the user can link a chat channel
openUrl Open an external page once the user confirms the address
reportError, rendered Report an error (falls back to the conversation), rendering finished

The microphone, camera and external maps aren't available in the first phase. If one is truly needed, work out how to open it safely, then add it to the bridge and the checks.

Data contract

The bot maintains app/state.json in its workspace, shaped by state.schema.json. The UI only reads it, and changes data only by asking the bot through send. That way, what a bot changes from a chat channel is already there when the user returns to the desktop.

Every catalog bot automatically gets the host-generated amb-app skill (src/botkit/app-skill.ts). It tells the bot how to read and write this state, how to handle UI actions, and how to reply in chat channels, so none of this belongs in persona.md.

Supported schema keywords: type, properties, required, additionalProperties, items, enum, const, minimum, maximum, minLength, maxLength, minItems, maxItems. Other keywords fail the checks.

Models don't always follow the contract, so files are validated on read. Invalid fields are removed, list items missing required fields are removed, the UI renders what it can, and the problem goes to the local log.

What the framework doesn't allow

These are runtime limits to design around:

  • No custom tools. A bot's abilities come from the model's built-in tools, skill instructions and scripts in its skills.
  • Scripts can't call the model or read the user's environment variables. Steps that need the model are done by the bot and its subagents (the agent tool). Use web_search for search; the host manages the search API and key from the app's settings.
  • Background tasks can only write to their own folder (tasks/<slug>-<id>/), so they can't write app/state.json. Long work that must update the view live runs in the current turn, which has a default limit of 30 minutes.
  • Results go back to the conversation that started the work. Start it in a chat channel and the result returns there; a bot can't pick another channel.

User flow

Action What happens
Open Downloads only the UI bundle and shows sample data labeled "Sample". No instance, skills, process or model call
First message (typed or a starter) Downloads the runtime bundle and verifies its sha256; creates instance cat-<id>; sample data becomes the initial state; the bot stays in Mine
After that Works like any bot, including in chat channels (/bot reaches it). It stays out of other bots' peer list
New version published Skills and UI are replaced on next open. Bots whose persona the user edited stop following the catalog; busy bots wait
Idle for 10 minutes The agent process exits and restarts on the next message
Remove Asks whether to keep the data. If not, the workspace and skills are deleted; if so, using it again picks up where it left off

A bot that was only viewed leaves nothing behind. Once newer bots push it out of the sidebar, it's still in Discover.

Checks

npm run bot -- check bots/<id>          # static: seconds, run after every change
npm run bot -- check bots/<id> --full   # optional: adds rendering and the real model; publishing doesn't depend on it
Category Rule prefix What it checks
Format format.* Required files, valid bot.json, no TODOs left, sample data matches the contract
Source source.* Imported skills have an author and source page, an allowed license (MIT, MIT-0, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, CC0-1.0), a matching hash, and no symlinks; the runtime bundle stays within the file count and unpacked size limits the client enforces
Permissions permissions.*, risk.* Network use must be declared; piping to a shell, deleting outside the workspace, reading secrets, obfuscated execution, persistence and privilege escalation always fail
UI ui.* No hardcoded colors, spacing or font sizes in CSS or JS; no inline scripts or external resources, and Link for external links; no network, storage or parent access; ≤ 500 KB compressed; matching zh-CN and en keys
Rendering render.* No errors, blank pages, overflow or contrast problems in light, dark and 390px
Behavior behavior.* Eval completion ≥ 80%, every starter changes the view, written state matches the contract
Security security.* Every prompt injection case passes

Failures name the exact rule. When a new kind of problem turns up, add a rule to src/botkit/check.ts.

Rendering, behavior and security only run under --full. --full is optional: packing and publishing don't depend on it. Running it needs two things:

  • Rendering uses Playwright, which isn't an app dependency: npm i --no-save playwright && npx playwright install chromium. Screenshots stay in .check/ and, once committed, become Discover thumbnails when packing. Without them, Discover cards show the avatar.
  • Evals connect to a running app: install Go 1.26.8+, run npm run setup && npm start, and sign in to Modelflare (--app <url>, by default the configured local port; set AMB_UI_TOKEN if it has a token). They really install the bot and call the model, then clean up.

Eval tasks go in evals/tasks.json: { id, prompt, changed?, contains?, notContains?, file?, files? }, at least 3. file: { name, text } puts a file in app/inbox/. files checks outputs against the files themselves: { match (a regex for the path), minBytes?, zipHas? (entries the zip must contain), absent? (no such file may exist) }. Nobody can click approvals during evals: the first-use prompt for a declared permission passes, everything else is denied, and the bot's questions get "go ahead with your recommendation". Injection cases go in evals/injection.json: { id, prompt, file?: { name, text }, mustNotContain }, at least 1.

Publishing and takedowns

The catalog repository looks like this:

bots/<id>/          One folder per bot
catalog.json        { "featured": [id…], "removed": { id: { reason, security? } } }
catalog.lock.json   Last published record per bot, maintained by pack; kept on the release machine
npm run bot -- pack --root . --out dist-catalog            # needs AMB_CATALOG_PRIVATE_KEY
npm run bot -- takedown <id> --root . --reason "why" [--security]
npm run bot -- who-uses <skill> --root .
  • pack runs the static checks on every bot and writes nothing if any fails. It produces index.json, index.json.sig, bundles/ and thumbs/. Putting them at the catalog URL publishes them.
  • Clients fetch at startup and every 6 hours (with ETag) and ignore anything that fails verification, including the local cache. UI and skills are verified by sha256.
  • After a takedown, run pack and publish again; clients pick it up within 24 hours. A normal takedown only notifies users. --security stops the process and deletes the skills right away, leaving the user's data alone.
  • .github/workflows/bot-catalog.yml checks and packs when bots/** or catalog.json is pushed to master, and keeps the output as a CI artifact. How it reaches production is up to the release environment. Until the repository has AMB_CATALOG_PRIVATE_KEY, it only checks and doesn't pack.

The live catalog

The app ships with the catalog's public key and address (src/botkit/config.ts). The address is https://anymodel.bot/catalog/index.json.

  • Private key: It's kept only on the release machine (AMB_CATALOG_PRIVATE_KEY) and never committed. Losing it means changing the public key and releasing the app again, so keep a separate backup.
  • Publishing: On the release machine, pull the latest master, run pack, and put the output at the catalog address. Adding or updating a bot doesn't need an app release unless the bot uses something only a newer app has.
  • catalog.lock.json: It stays on the release machine and goes back in the repository root before each pack.
  • Website: The /bots page comes from site/src/data/catalog-bots.json. After adding a bot or changing its text, run npm run sync in site/, commit, and deploy the website.
  • Turning the catalog off: Set AMB_CATALOG=off. The app stays off the network for this, and the catalog is empty. Tests run this way.

To test locally without changing code, set AMB_CATALOG_URL and AMB_CATALOG_PUBKEY.

Building bots with Claude

.claude/skills/amb-bot-dev/ is the bot dev skill, which turns these rules into steps for Claude. Tell Claude what to build; it scaffolds from the template and works until check passes. A future batch pipeline would just be one more author, and its output would pass the same checks.

APIs

All under /amb/api. Errors only return a code; the text lives in the UI dictionary at botapp.errors.*.

API Purpose
GET /catalog List the catalog
POST /catalog/sync Sync now
POST /catalog/dev, DELETE /catalog/dev/:id Register or remove a local folder (loopback only)
GET /catalog/:id One entry
POST /catalog/:id/preview Prepare the UI and return its URL, without an instance
GET /catalog/:id/file?path= Read sample data when there's no instance
POST /catalog/:id/install Create the instance
GET /bots/:id/app Instance source, version, whether an update exists
POST /bots/:id/app/update Update
GET /bots/:id/app/file?path= Read a file under app/
GET /bots/:id/app/image?path= Read an image under app/ as a data URL
GET /bots/:id/app/list List files under app/ (used by evals)
GET /bots/:id/app/download?path= Download a file under app/
POST /bots/:id/app/open Desktop app: open a file under app/ or show it in its folder
POST /bots/:id/app/inbox Put a file in app/inbox/
GET /bots/:id/app/watch SSE: file changes under app/

Static files are under /amb/botapp/: kit/ (kit and design system), b/<sha256>/ (UI bundles), d/<id>/ (dev folders), thumb/<sha256> (thumbnails). This path needs no token, because sandboxed pages can't send cookies, and it holds no user data.