Install the Miblo SDK (TypeScript and Python) and get a token

Before you start#

• Miblo installed on the computer (with the app or the command line), with the miblo command in your terminal. Check with miblo sdk status.

• Node.js 20+ for the TypeScript package, or Python 3.9+ for the Python package.

• A Miblo on your desk is optional. With no gadget paired everything works, and actions answer delivered: 0, which is not an error: sessions still show in the Miblo app and on the phone.

Install the package#

The packages come only from miblo.ai, version 1.4.0. They are not on npm or PyPI: install straight from the address.

TypeScript / Node.js#

@miblo/status: ESM, typed (index.d.ts), no dependencies.

npm install https://miblo.ai/dl/sdk/miblo-status-1.4.0.tgz

Python#

miblo-status: standard library only.

pip install https://miblo.ai/dl/sdk/miblo_status-1.4.0-py3-none-any.whl

Check the download#

Each file has its Ed25519 signature next to it (the same name with .sig), made with the key of Miblo's updates, and the signed SHA256SUMS lists every version.

curl -fLO https://miblo.ai/dl/sdk/miblo-status-1.4.0.tgz
curl -fsSL https://miblo.ai/dl/sdk/SHA256SUMS | shasum -a 256 -c --ignore-missing

The token#

The Status API is off until you create its token. In your own terminal:

miblo sdk token            # turns the API on and prints the token (miblo_sdk_ + 64 characters)
export MIBLO_TOKEN=$(miblo sdk token)

Prefer no terminal? In the Miblo app → Programs (SDK) you turn the API on, copy the token and replace it.

• The packages read the token from MIBLO_TOKEN (or take it as a parameter: new MibloStatus({ token }), MibloStatus(token=...)). Hand the token to your program on purpose; a program should not go looking for Miblo's files.

• miblo sdk token --rotate replaces the token: whoever held the old one is refused from then on (not_authorised), and your AI tools, the CLI and the phone are not affected.

• miblo sdk off deletes the token and turns the API off (sdk_off). miblo sdk status says whether it is on and where the file is.

• The bridge must be running. Your AI tools start it, and so does miblo sdk start.

First program#

Ten lines: the program shows up as a session, works, says it needs you and finishes.

// MIBLO_TOKEN=$(miblo sdk token) node first.mjs
import { MibloStatus } from '@miblo/status';

const miblo = new MibloStatus();                          // reads MIBLO_TOKEN
const job = await miblo.session({ tool: 'first.mjs', title: 'Deploy', detail: 'building' });
await new Promise((r) => setTimeout(r, 5000));            // ...your work...
await job.needsYou('confirm the deploy');                 // Miblo alerts
await new Promise((r) => setTimeout(r, 10000));
await job.done('deployed');

# MIBLO_TOKEN=$(miblo sdk token) python3 first.py
import time
from miblo_status import MibloStatus

miblo = MibloStatus()                                     # reads MIBLO_TOKEN
job = miblo.session("first.py", title="Deploy", detail="building")
time.sleep(5)                                             # ...your work...
job.needs_you("confirm the deploy")                       # Miblo alerts
time.sleep(10)
job.done("deployed")

What happens:

1. session() registers the session Deploy on the gadget, in the Miblo app and on the phone, with the line first.mjs · building.

2. needsYou() moves it to needs you: the gadget gives the question alert and the "needs you" counter goes up. On the phone, the session shows as Other tool: first.mjs.

3. done() shows it as finished, with the finished alert. When the process exits, the session goes by itself (the package sends its own process's pid).

Let Miblo run your program#

For a program that is always on (a screen app, a watcher), let Miblo's supervisor look after it. In your own terminal (an AI agent cannot do this for you):

miblo apps add "node steps.mjs" --cwd ~/code/steps --id steps
miblo apps enable steps        # starts it now and every time Miblo starts
miblo apps logs steps          # what the program printed

• Miblo starts the program with MIBLO_TOKEN, MIBLO_PORT and MIBLO_APP_ID (the app's id), plus MIBLO_LANG (pt or en) and the system's basics (PATH, HOME, language, time zone, proxy). Nothing else from your environment goes along: keys in your shell never reach the program.

• Without --id, the id comes from the file name (steps.mjs → steps). Use the same id the program declares in app.declare(). Without --cwd, it runs in the folder you added it from.

• If the program exits, Miblo starts it again after 2 s, 10 s, 30 s, 2 min and 10 min. While an app is on, the bridge stays up.

• miblo apps show <id> shows its state and how many times it restarted; miblo apps disable <id> turns it off; miblo apps remove <id> turns it off, takes its screen away and forgets the program and its settings.

• miblo apps list shows them all (the official ones, yours and the community's). In the Miblo app, the Apps tab does the same with a switch per app.

Start an app: two paths#

For a store app (a screen, or alerts people turn on with one click), start from the ready-made template and watch it in the simulator, with or without a Miblo on your desk:

• With Miblo installed: miblo apps new "My App", then miblo apps dev my-app (the screen in your browser, reloaded on every save) and miblo apps check my-app (the store's rules).

• Without Miblo: download the starter https://miblo.ai/dl/extras/miblo-app-starter-1.28.0.zip and use node sim.mjs new | dev | check (Node 22.15+ or 24+).

The details are in Develop without a Miblo.

When something goes wrong#

Every error is a MibloError with a stable code. The ones you meet while setting up:

The other codes are in Sessions and status and The App screen.