Phone, chat and editor — Mirasim Guide

Every surface Mirasim ships#

Your Mac is normally the host and the source of truth. Everything else is a way into that host: paired Android clients and configured IM channels enter through their own transports, the VS Code extension embeds a host of its own, and the desktop can instead point at a self-hosted macOS or Linux server.

What each surface is for

Desktop: The primary multi-agent workbench and local host. Apple Silicon macOS DMG, macOS 13+.
Android: Paired companion for sessions, prompts, decisions, notifications and transcript images. Signed APK, Android 8.0+.
iPhone: The same companion on iOS, still in closed testing: it ships through TestFlight, Apple's beta channel, and the public invite is not open yet. iOS 15+.
CLI / TUI: Built-in agent, transparent Claude/Codex launches, host control, accounts, diagnostics, automation. Standalone darwin-arm64 archive.
VS Code: The shared workbench inside the editor, running its own embedded host. .vsix, VS Code 1.90+.
IM channels: Remote prompts, live progress, human-in-the-loop decisions and artifact replies: Telegram, Feishu, Slack, Discord, DingTalk, WeCom, Weixin.

The Android companion#

Install the signed APK, pair it with your host, and you can read sessions, send prompts, answer the decisions that are blocking work, and get notified when something needs you — from wherever you are. Pairing is keyed: when the pairing code carries the host's end-to-end public key, the connection uses application-layer end-to-end encryption.

Enable remote access on the host
In Settings, Connection: this machine can stay local, be reachable on your LAN, or be reachable over the internet through a relay address. If the machine has a public address, enter it and clients connect directly instead.
Pair the phone
Scan the host's code from the app, or paste the connection code. The code contains the access token — share it only with people you trust.
Use it as a companion, not a second workbench
The phone is built for the moves that are worth making one-handed: read what happened, answer a question, queue the next prompt, unblock a decision.

Settings on the phone has a Run account row: which subscription account the conversations on that machine run under, each identity shown with its usage. Switching takes effect from the next turn — the turn already running keeps the account it started on. Adding an account means pasting a credential, which is a job for the computer; the phone only picks between the accounts you already have.

The phone can also update the computer it is paired with, which is worth knowing when the machine is at home and you are not. It asks before doing it, because applying an update restarts the app on that desk and drops this connection — the reconnect is how you know it worked.

A pairing is meant to outlast the network it was made on. The phone dials the LAN first when both are on it and falls back to the relay address elsewhere, and the host finds that address itself rather than asking you to configure one. When the phone temporarily cannot reach the machine, the panel says so and the link reconnects on its own — you do not pair again. The credentials behind it are stored encrypted and signed against the device they were issued to, so a copied credential does not work somewhere else.

IM channels#

Connect a chat platform and your workspace becomes reachable from a conversation: send a prompt, watch progress, answer a decision, get artifacts back. Every supported channel uses a long-lived connection mode, so none of them needs a public IP or an inbound webhook.

Seven channels, each with its own credential shape

Mirasim

Default

8%

checkout-api

design-system

docs-site

infra

mobile-app

storefront

infra

/New Session

Type a prompt — paste or drop files too

~/code/storefront

The Mirasim IM settings screen listing the supported chat channels and what each one still needs configured.

All sevenEach row states plainly whether it is connected and what is still missing — so a half-configured channel is visible rather than mysteriously silent. — this control is not on the captured screen.

The buttons in this panel work — click them to look around.

What each channel needs

Channel	What you provide
Telegram	A bot token from @BotFather; optionally a list of allowed chat IDs to restrict who can use it.
Feishu	An app's App ID and secret, the bot capability enabled, the IM scopes imported, and events plus callbacks both set to long-lived connection mode.
Slack	Socket Mode enabled with an app-level token, plus a bot token and the message and mention event subscriptions.
Discord	A bot token with the message content intent enabled, and the bot invited to a server.
DingTalk	Client ID and secret from an internal or chatbot app, with the chatbot capability on and events on Stream Mode.
WeCom	A Smart Bot's ID and one-time secret from the admin console; the channel then holds a long-lived WebSocket open.
Weixin	A QR sign-in confirmed on your phone; the channel enables only after validation succeeds.

Each channel's setup panel walks its own steps in order and validates the credentials before it enables anything, so a mistyped secret fails at setup rather than three days later. You can also validate a channel at any time from the CLI.

Configure and check a channel headlessly

mirasim ui-cli --port 4970 im validate --channel feishu
mirasim ui-cli --port 4970 config set im.feishuAppId=cli_xxx im.feishuAppSecret=yyy

The VS Code extension#

The extension puts the shared workbench inside your editor and runs its own embedded host, following the workspace VS Code already has open. If your day is spent in the editor, this is the version of Mirasim that does not ask you to leave it.

Using another machine as the host#

The Connection page decides which machine this console controls: this computer, another on your LAN by address, or a remote one by connection code. The same page can also share this machine — enable server access, then hand the connection code to someone you trust.

You do not have to take the connection code apart yourself. Paste it into either field — address or token — and it splits into the two halves it carries. If it turns out to hold no directly reachable address, only the token is filled in and the page says which half is missing. Sharing a machine offers the token on its own as well, next to the code, because another desktop connecting in wants just that.

Remote entries authenticate with a bearer token and do not carry an Android pairing's E2E key — use HTTPS/WSS or a trusted network.
Selecting a remote host does not migrate the local host's pairings, IM configuration or schedules; those belong to the host that holds them.
Work follows the host: files, Git worktrees, session history, artifacts, recordings and usage data live where the host lives.

A Linux box over SSH#

A Linux machine does not need Mirasim installed beforehand. Give the Connection page an SSH target and Mirasim probes the machine, copies the server build over, starts it there and tunnels it back — no ports opened on the remote side. Close the window and the agents on that machine keep running.

Sign in with your SSH agent, a password, or a private key. The agent option reuses your ssh-agent and ~/.ssh/config, so it behaves exactly like typing ssh in a terminal. A password is stored only on this computer, encrypted by the system keychain.
Hosts already in your SSH config are listed for you, so you do not have to retype names this computer already knows.
A bastion host and per-machine environment variables are available under the advanced options — the environment variables are passed when the server starts on that machine.

The same thing from a terminal

mirasim ssh ubuntu@dev.example.com   # connect, tunnel, stay in the foreground
mirasim ssh list                     # saved machines and their status
mirasim ssh stop dev.example.com     # stop the server on that machine