Skip to content
miblo

SDK

Miblo SDK: your programs and apps on the Miblo screen

The Miblo SDK docs: the Status API on your computer, the token, the App screen, apps and publishing to the store. TypeScript and Python; nothing leaves your computer.

What it is

The Miblo SDK lets your own programs show up on Miblo: a build script, a data job, a bot that watches a website, an AI tool Miblo does not connect. A program can:

  • become a session on the gadget, in the Miblo app and on the phone (working, needs you, idle or done), with an alert when it needs you;

  • put a short message on the screen, start a focus session (Pomodoro) or a timer;

  • draw the App screen, a screen of Miblo's rotation that is all its own: a card with numbers, rings, bars and charts, a background image, or both;

  • become an app: with a name, settings the person fills in the Miblo app, and Miblo taking care of running it. Miblo's official apps (Processor, Bitcoin and Crypto and the ones each release brings) are exactly that.

The SDK does status and nothing else. It does not approve, reply or start tasks in your AI tools, and nothing in it turns those on. It is Miblo's rule: it shows, it never interferes.

There are two packages with the same API: @miblo/status for Node.js 20+ (TypeScript, typed, no dependencies) and miblo-status for Python 3.9+ (standard library only). Any other language can speak the same protocol: it is all in the reference.

How it works

How a program reaches the Miblo screenYour computerNothing from your program goes to miblo.aiYour programTypeScript or PythonMiblo bridgeon your computerStatus API v1127.0.0.1:47821token + HMACMiblo on your desklocal network, pairedMiblo app and phonethe same status, encrypted
How a program reaches the Miblo screen

  1. The Miblo bridge is the Miblo process already running on your computer: it talks to your AI tools, to the gadget and to the phone. It opens the Status API v1 on 127.0.0.1:47821 only, your own machine.

  2. Your program talks to the bridge over local HTTP, with a status-only token you hand to it (miblo sdk token). Every request carries a single-use challenge signed with HMAC-SHA256, and every answer comes back signed: the program knows it talked to Miblo, and the bridge knows the program holds the token.

  3. The bridge checks everything (sizes, limits, Miblo's reserved phrases) and passes it on to the gadget over your local network, with its pairing, and to the Miblo app and the phone along with the status they already get (end-to-end encrypted on the phone).

  4. The gadget draws. A card becomes pixels on the Miblo itself, with its own fonts and colours; an image is converted on the computer into Miblo's format before it goes.

The token

The token (miblo_sdk_ + 64 hex characters) is separate from the bridge key: it only reaches the /sdk/v1/* routes. With it a program shows status; it cannot read commands, prompts, files, costs or anything of Miblo+, cannot approve anything and cannot change the gadget's settings. If it leaks (a CI log, a shared script), the leak is limited to status, and miblo sdk token --rotate ends it.

Get the token in a terminal (miblo sdk token) or in the Miblo app → Programs (SDK). The details are in Install.

What you can do

I want to...UsePage
Show my script is running and get alerted when it needs mesession(), needsYou(), done()Sessions and status
Put a message, a focus session or a timer on the gadgetsay(), focus(), timer()Sessions and status
Know who is working and who needs mesnapshot()Sessions and status
Draw a screen of my own with numbers and chartsscreen.card(), screen.layer()The App screen
Have settings the person fills in the Miblo appapp.declare(), app.settingsApps and settings
Read the person's Google or Microsoft calendarapp.connectApps and settings
Let Miblo keep my program runningmiblo apps addInstall
Publish my app to the storemiblo.ai/appsPublish to the store

Where to start

  1. Install the package and get the token, then run your first program (10 lines).

  2. Read Sessions and status for alerts, and The App screen to draw.

  3. Want other people to use it? Make it an app and publish it.

Versions

  • API v1 never breaks: fields are only ever added; none is removed or changes meaning, and no limit gets stricter. An incompatible change would go under /sdk/v2/, with v1 kept alongside.

  • The packages follow semver, and every 1.x speaks v1. The App screen needs Miblo 1.25 or newer on the computer and on the gadget (an older gadget answers unsupported).

  • The packages come only from miblo.ai (they are not on npm or PyPI), with an Ed25519 signature next to each file.