Mobile app

Maestrly for iOS and Android follows and directs your bots, and the chats and workspaces of your bot server's workspaces environment, from your phone. It needs a bot server (see Bots and the bot server); it does not connect to the desktop app on your computer directly.

The mobile app is new in Maestrly 0.19.0. Update the bot server first: a server that predates phones cannot pair one.

Get the app

Mobile builds are not attached to GitHub Releases, which carry the desktop installers only, and store links are not published yet. Developers can build the app from apps/mobile in the repository, as the technical guide describes.

To try the app without a server, choose Explore a demo server on the first screen. It opens a sample server with bots, chats and workspaces that lives in the app; nothing in it leaves the phone.

What it does

Bots: see every bot by environment, with what it is doing now and what waits on you. Read a bot's conversation as it streams, scroll back through older messages, and send text, photos and files.
Chats and workspaces: the menu's Chats and Workspaces tabs list those of the server's workspaces environment. Open a chat, start a new one on its own or in a workspace, and change its mode, model, effort, skills, MCP servers and context limit. When an agent starts conversations from a chat, a card lists them, each with a way to open it.
Interactive answers: an interface in a reply shows as a card, and the phone never runs it. Use it in Maestrly on your computer, or read its source with Show code.
Requests: approve or deny a command, answer a question, or mark a request for help as resolved. In a chat, you can also review a plan and confirm the conversations an agent wants to start.
Setup: change a bot's model, reasoning effort, Fast mode and permissions; start, pause, resume, restart or stop a bot; run a routine now; compact a bot's conversation. New chats start with the defaults you choose in Settings → New chats.
Notifications: hear when a bot or chat needs you, finishes a turn you started, finishes a routine, or fails.
Dictation: the microphone in the message field turns what you say into text with the phone's own speech recognition.
Artifacts: a page an agent publishes shows as a card in the conversation, and Open shows the version it published.
Offline: a message you send without a connection shows Not sent yet, waits on the phone, and goes out in order when the server is reachable again.

Creating bots, connecting model accounts, installing skills, adding MCP servers and managing routines stay in Maestrly on your computer. A phone never reaches the server's files, terminals, accounts or settings.

Requirements

A phone reaches the bot server over HTTPS. iOS and Android refuse plain HTTP, so an address that works on your computer, such as an SSH tunnel on http://127.0.0.1, does not work on the phone. The simplest way is Tailscale Serve on the server and Tailscale on the phone; the bot server technical guide shows how for a server you manage.

Chats and workspaces need the server's workspaces environment to run a version of Maestrly that offers the mobile API. The phone does not need the same version as the server, only the same mobile API. A server with several workspaces environments shows the phone the chats of one of them: the first that runs and speaks to phones. See Remote workspaces and chats.

Pair

On a computer already paired with the server, open Settings → Bot server and choose Pair a phone.
Check the Address your phone uses field: it must be the server's https:// address.
In the app, choose Scan pairing code and scan the QR code. The app shows the server's address and asks you to confirm before pairing.

Without a computer at hand, run maestrly-bot-gateway pair on the server and choose Enter code manually in the app. Codes work once and expire after ten minutes. Any paired device can create codes for other devices, at most five unused at once.

A paired phone sees and directs every bot on the server, so pair only phones you trust.

Notifications

After pairing, the app offers to turn notifications on. Settings → Notifications in the app chooses what you hear about, for every paired server:

Category	When
Waiting on you	A bot or chat asks for approval, asks a question, has a plan for you, or needs help.
Replies	A bot or chat finishes a turn you started.
Routine reports	A bot's routine finishes.
Problems	A turn fails, or a bot stops unexpectedly.

Send a test notification asks the server for one. A notification for the conversation already on screen shows no banner, and tapping a notification opens its bot or chat on the server that sent it.

The server sends notifications through Expo's push service, which hands them to Apple or Google. A notification carries the bot's name or the chat's title and a fixed phrase, such as "Needs your approval", in the phone's language. It never carries what a bot, chat or person wrote.

On a server you manage, set MAESTRLY_GATEWAY_PUSH=off in its .env to send none; the phones say so in their settings. Notifications need a real phone: simulators and the web preview cannot receive them, and a build you make yourself needs an Expo push project, as the technical guide explains.

Artifacts

Pages open in the system's browser view through the server's public address, which must be HTTPS. Set it on your computer in Settings → Artifacts → Public address. Each Open asks the server for a single-use ticket that expires within a minute, as the desktop does. The page's scripts run in the browser view, never in the app. See Artifacts.

Unpair and revoke

In the app, open Settings and choose Unpair from followed by the server's name. If the server cannot be reached, the app offers Forget anyway; the server then keeps listing the phone until you revoke it with devices revoke <id> on the server. A revoked phone shows "This phone was removed from" and the server's name, and offers Pair again. Unpairing or revoking a phone also removes its push registration from the server.

Privacy and data on the phone

The device token for each server is in the iOS Keychain or the Android Keystore, readable after the first unlock and never moved to another device.
The list of paired servers, your theme, language and notification choices, the defaults for new chats, and messages not yet sent are kept in the app's storage. Photos and files waiting to be sent stay in the app's cache until they are.
Each server keeps the phone's push token and notification choices until the phone unpairs or is revoked.
The app talks only to the servers you paired and, when you turn notifications on, to Expo's push service and to Apple's or Google's to get a push token. It sends no telemetry.
Dictation uses the phone's speech recognition: Apple's on iOS, Google's (or the phone maker's) on Android. They may process the audio on their servers, under their own privacy policies. Maestrly and your server receive only the text you then send, never the audio. The microphone is on only while the listening indicator shows.

See the privacy document for the whole application.

Troubleshooting

You see	What to do
Can’t reach the server	Check that the address is `https://`, that the phone reaches it (with Tailscale, it runs on both and they share a tailnet), and that the phone's clock is right.
Update the bot server to pair a phone, on the computer	The server predates phones. Update it, or run `maestrly-bot-gateway pair` on it.
This code has expired	Codes last ten minutes and work once. Create a new one.
This phone was removed from a server	The phone was revoked or unpaired elsewhere. Pair it again.
This server runs a version this app can’t use	Update the bot server and the app.
The workspaces host isn’t running	Start the workspaces environment from Maestrly on your computer. Messages you send wait on the phone.
Update the bot server to use chats on this phone	The server or its workspaces environment predates the mobile API. Update both.
Update this app to use chats on a server	The server's workspaces environment uses another version of the mobile API than the app.
A notification setting says the server sends no notifications	The server sets `MAESTRLY_GATEWAY_PUSH=off`.
Pages do not open	Set an HTTPS Public address in Settings → Artifacts on your computer.

For the build, release and device checks, read the full technical guide.

Next: Artifacts.