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, video, 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.

Use your device

No camera, no location, no reading your clipboard, no notifications. The microphone is the one exception — and even there the app never touches it directly; Catalyst listens on its behalf (below).

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.
  • The microphone — an app can hear you: live transcription while you talk, or a recorded clip it hands to a workflow. Catalyst does the capturing, with your permission — see below.

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

Listen to the microphone

Section titled “Listen to the microphone”

The sandbox has no microphone of its own — inside it, getUserMedia and the browser’s speech recognition simply don’t work, and no setting changes that. So Catalyst listens on the app’s behalf: the Catalyst page captures the audio and passes the app either live transcript text (catalyst.speech.listen()) or the recorded clip (catalyst.audio.record()). The app gets words and audio; it never gets your device.

What that looks like when you use one:

  • You’re asked once. The first time an app listens, your browser asks for microphone permission — for catalyst.voov.ai, the same prompt voice mode uses. Allow it once and later apps don’t ask again.
  • You can see it, and stop it. While an app is listening or recording, Catalyst shows a small Listening pill naming the app, with a Stop button. Nothing captures silently.
  • Closing the app stops the mic. Capture ends the moment you close the app — an app can’t keep listening behind your back.
  • Two engines, and they differ on privacy. The browser engine uses the speech recognition built into Chrome, Safari, or Edge — many languages, including Hindi and Indian English, but the audio is transcribed by Google or Apple. The platform engine is Catalyst’s own speech-to-text, the same one voice mode uses: English only, and the audio stays on the workspace rather than going to a third party. An app can pin either one, or ask for 'auto' and take whichever is available.

A recording is just audio, so the app can hand it to a workflow as a file, the same way it would a photo or a document. And since all of this lives in the SDK, you get it by asking: “Build a dictation pad that transcribes what I say in Hindi” is enough of a brief.

Section titled “Related”