Companion

Companion mirrors your MadoHub canvas onto the iOS app over your local Wi-Fi. Walk away from your desk and keep an eye on your agents from your phone; send a quick keystroke or kick off a flow without coming back to the keyboard.

It is a LAN mirror, not a cloud relay. Nothing about your canvas, your agents, or your terminal output passes through a MadoHub server. The Mac runs a small server on your local network and your phone connects to it directly, staying in sync as long as both are on the same Wi-Fi.

What you can do with it

• View your canvas from your phone — every frame, tile, agent status, activity line, and a recent tail of terminal output, in read-only form.
• Open a tile to read its full terminal detail — the phone shows the same tile states the desktop uses (idle, working, waiting, stopped, completed, failed, exited).
• Send keystrokes to a tile — free text, plus escape, ctrl-c, and enter as special keys, delivered the same way they would be if you typed locally.
• Create a terminal or frame from the phone — spin up a new terminal at the desktop viewport center, or open a workspace frame by path.
• Run a flow remotely — instantiate a Flow from the phone with a task prompt, and the desktop kicks it off.
• Reset the pairing token — immediately invalidate every paired device from Settings if a phone is lost or you want to start over.

How to use it

1. Open Settings → General on the Mac and enable Companion.
2. The settings panel shows your Mac's local IP and port (for example 192.168.1.23:9280), a pairing token, and a madohub://companion?… link you can copy to the phone.
3. Open the link on your phone (or enter the address and token manually in the iOS app).
4. The phone pairs and starts mirroring the canvas. Settings shows how many devices are currently connected.
5. From the phone, tap a tile to read its detail, send input to a tile, or use the menu to create a terminal, open a frame, or run a flow.

To unpair everything, click reset token in Settings. Every paired device is immediately invalidated; if the server is running it restarts under the new token.

Common use cases

• "Keep an eye on a long-running agent from the couch." — open the phone, watch the tile's status and recent output, send ctrl-c if it goes off the rails.
• "Kick off a peer review flow without walking back to the desk." — from the phone, run the Peer review flow with a task prompt.
• "Approve a permission prompt from across the room." — tap the tile, send y or enter to unblock the agent.

Tips and best practices

• Both devices need to be on the same Wi-Fi. Companion does not work over the internet or across subnets.
• The canvas mirror is read-only — you can view tiles and send input, but not drag tiles or rewire connections from the phone.
• Reset the token if a paired phone is lost or you change networks. The new token invalidates all previous pairings immediately.
• The server tries port 9280 first and falls up through 9299 if that is taken, so the exact port may differ across machines — copy the link from Settings rather than guessing.

Security and privacy

• LAN-only, no cloud relay. Your canvas, agents, and terminal output stay on your local network; nothing passes through a MadoHub server.
• Pairing uses a token + challenge-response, not a bearer token on every request. The token itself never crosses the wire; only a salted response to a fresh per-connection challenge does, so a captured response cannot be replayed against a later connection.
• No one can write without the token. A passive observer on the same Wi-Fi can read mirrored traffic (there is no TLS yet), but they cannot open an authenticated session of their own or inject input without the token.
• The server bounds itself against a hostile LAN — at most 64 concurrent connections, and an authenticated client that goes silent for 60 seconds is dropped so it cannot pin a connection slot indefinitely.

Related features

• Flows — run a flow remotely from the phone.
• Settings — where you enable Companion and reset the token.
• Team Collaboration — for monitoring team members rather than your own canvas.

Limitations

• Companion requires both devices on the same local Wi-Fi. Off-LAN use (over the internet) is not supported yet.
• There is no TLS on the connection. A passive observer on the same LAN can read mirrored traffic; active man-in-the-middle attacks are not addressed yet.
• The canvas mirror is read-only — you cannot drag tiles or rewire connections from the phone.
• Companion currently requires a Mac host. There is no Windows host support yet.