Skip to content
Catalyst Docs

How mini apps run

A mini app is a small program the assistant wrote for you, and it runs in your browser. Because it’s generated code — and because apps can be shared, forked, and published — Catalyst runs every app walled-in. It’s the same idea as opening a document in a viewer: you can use it, but it can’t reach into the rest of your stuff.

Understanding that wall explains everything else — why some libraries work and others don’t, and why an app can only touch the data you point it at.

The architecture

Section titled “The architecture”
You ──ask──►  Catalyst  (your account: login, data collections, workflows)
                  │
                  │  hosts the app and brokers its requests — checking your grants
                  ▼
        ┌──────────────────────────────────────────────┐
        │  Sandboxed frame                              │
        │  the assistant's app code runs here           │
        │                                               │
        │   ✗  can't see your account or login          │
        │   ✗  no internet access                       │
        │   ✗  no browser storage                       │
        │                                               │
        │   ✓  one door out: the catalyst.* SDK ────────┼──►  your GRANTED
        │      (run a workflow, read/write a collection) │      workflows & data
        └──────────────────────────────────────────────┘

Three layers, top to bottom:

  • Catalyst (your account) holds your login, your credentials, your data collections, and your workflows. The app never sees any of this directly.
  • The sandboxed frame is where the app’s code actually runs. It’s isolated from your account — no cookies, no login, no way to read the page around it — and it can’t reach the internet or save to your browser.
  • The catalyst.* SDK is the only way the app reaches anything beyond itself, and every call goes back through Catalyst, which checks the app’s grants before it runs. The app’s code never holds your credentials — Catalyst does the work on its behalf.

What an app can’t do

Section titled “What an app can’t do”

These are the restrictions that fall out of the sandbox:

Reach your account

The app runs isolated — it can’t read your login, your cookies, or the Catalyst page around it.

Use the internet

An app can’t make its own web requests, so most network libraries (HTTP clients, cloud SDKs) don’t work inside one. (External images and map tiles are a narrow, grantable exception — see below.)

Save to the browser

There’s no localStorage or IndexedDB. To remember anything, an app uses a data collection (below), not the browser.

Touch ungranted data

An app can only see the collections and workflows you explicitly hand it — nothing else in your account is reachable.

What an app can do

Section titled “What an app can do”

Everything that runs inside the app is fair game — UI, charts, 3D, animation, parsing, search, math — using the built-in or added libraries. To reach beyond itself, it uses Catalyst through the SDK:

  • Data collections — the app’s storage, in place of browser storage. “Save my entries,” “remember my list.”
  • Workflows — the app’s verbs. Anything that needs the outside world — calling an API, searching the web, generating an image — happens in a workflow the app runs, where your credentials and grants apply.

You decide exactly which collections and workflows an app may use when you build or grant it — see Data & permissions for how that works.

Section titled “Related”