Your phone
A phone cannot run agents or reach your hosts over ssh, so it uses a computer that stays on, the hub. Any mocante device can be the hub. The phone sees the hub’s sessions, types into its terminals and answers its agents.
The hub and the phone meet at a relay. The hub keeps one outbound connection to the relay and never listens on the network. Traffic between the phone and the hub is end-to-end encrypted: the relay passes bytes it cannot read.
Turn on hub mode
Section titled “Turn on hub mode”- On the computer that stays on, open Settings and go to Hub.
- Enter the relay address, such as
wss://relay.example.com. - Turn on Hub mode. The status line under the address says when the hub is connected to the relay.
Hub mode needs a relay address before it turns on. The address must start with wss://. Plain ws:// works only for a relay on the same computer, because the phone loads mocante’s page from the relay, and a page sent without encryption can be replaced on the way. If hub mode cannot start, the status line says why.
If the status says another mocante took over the relay, a second copy of mocante with the same hub key connected. This happens when two copies share one configuration folder. Only one hub can hold the relay at a time, so this copy waits: it does not send notifications or pair devices. It checks every 10 minutes whether the relay is free again, as after the other copy quits, and then takes it. To take the relay back at once, turn hub mode off and on again.
Pair the phone
Section titled “Pair the phone”- In Settings › Hub, select Pair a device. A QR code and a link show.
- Scan the QR code with the phone, or open the link on it. The code works once and expires after two minutes. A link with a wrong code does not use up the code, so you can try again with the correct link.
- The phone opens mocante and shows a six-digit code. Settings › Hub asks whether to allow the phone, by its name, and shows a code too. Select Allow only if the two codes match. If they do not, another device used the QR code: select Refuse. Refuse, or no answer within a minute, stops the pairing and uses up the code.
- The phone pairs. The hub shows a notice, and the phone appears under Paired devices.
To remove a phone, select Remove beside it under Paired devices. Its connections close at once, and it must pair again.
The phone forgets its pairing only when the hub itself says that it does not know the phone, as after Remove. The relay cannot say it for the hub. Then the phone shows the welcome page with the reason. When the hub is offline, slow or busy, or the relay refuses the connection, the phone keeps its pairing and tries again. If a paired phone fails to pair again from a new link, it keeps its old pairing.
If you open a pairing link for a different computer or relay on a phone that is already paired, mocante asks before it replaces the pairing. Only continue if the link came from your own computer’s Settings › Hub: a link from someone else would connect the phone to their computer. A new link from the same computer pairs again without asking.
The phone remembers the relay address from its link. If you change the relay address on the hub, pair each phone again. Until you do, the phone finds the hub offline. A new hub key also needs a new pairing.
On the phone
Section titled “On the phone”The phone shows one pane of a session at a time. The session header switches panes and opens the command palette. Swipe right from the left edge of the screen, or tap the menu button, to open the sidebar. In a session, swipe left from the right edge, or tap the panel button beside the search button, to open the git panel. Under the terminal, a key bar gives you the keys a phone keyboard does not have: Esc, Ctrl, Tab, Shift+Tab, Ctrl+C and the arrows. Its keyboard key shows the keyboard, and hides it when it is open. Swipe up or down on the terminal to scroll its history, as a mouse wheel does on the desktop.
The code pane starts with the file tree hidden, so the file gets the full width. The button left of the file name shows it. This choice stays on the phone and does not change the file tree on your other devices.
On an iPhone or iPad, a link you tap in mocante, or a link that a program in a session opens, shows a sheet first:
- Open in Safari opens the link in Safari. Switch back to mocante to read a one-time code or other text in the terminal, and the page stays open in Safari. Some iOS versions do not let mocante open Safari. If nothing happens, the sheet stays open: use Copy link.
- Copy link copies the link, so you can paste it in Safari.
- Open over mocante opens the link in the sheet iOS shows over a home screen app. That sheet covers the terminal, and the page closes when you close the sheet.
The browser pane lists the pages open in the desktop app’s browser for the session. Tap a page, or type an address and tap Open, to open it in the phone’s own browser. A page on localhost opens at the host’s hostname, so the host needs a hostname that the phone can reach, such as its Tailscale name.
The phone has no pop-out windows, so the pop-out button and commands do not show there.
Some settings change only on the hub’s own screen. A phone cannot pair, allow or remove devices, change the relay address or turn hub mode on or off, or change the 1Password settings and tokens, including the token and the vaults of a host. A phone never sees an open pairing code. If it tries, the hub refuses and says that the change works only in a window of the app. Everything else, including review threads and sending them to agents, works from the phone.
The command palette’s git actions, such as commit and push, open the git panel from the right.
When the phone loses its connection to the hub, a reconnecting… bar shows under the session header. What you see is the last state the hub sent; tap the bar to reconnect at once.
Shared images and videos show in the shared pane. Other shared files, SVG images included, download instead of opening in the browser. If a shared file cannot load, the pane says why, and it tries again when the phone reconnects.
The scratchpad takes the whole screen. The list button shows your notes over the note, and picking a note hides the list again. See scratchpad.
When you come back to mocante after a new version was deployed, a notice names the new version and the one you are on, with a Reload button. Tap it to load the new version. mocante does not reload by itself, so nothing you type is lost.
When you switch to another app or lock the phone, mocante disconnects from the hub. When you come back, it connects again, gets the current state and attaches to the terminal again. If a connection is lost while mocante is open, as when the network drops, the hub keeps what it sends for a short time. If a session sends a lot of output in that time, the hub stops sending, and the phone connects again.
Approve from a notification
Section titled “Approve from a notification”When Claude Code or Codex asks to run a tool, the notification names the tool. Tap it to open an approval card with the command and Approve and Deny buttons. Your answer goes to the agent, and the terminal stays open behind the card. Open the terminal closes the card and hands the question back to the agent’s own prompt.
A request to read 1Password secrets opens the same card, which can only deny it. To approve it, open the session on a screen that lists every reference.
The notification and the card stay private: a push service carries only encrypted data for your phone, and the relay carries only encrypted data between your phone and your hub.
Notifications
Section titled “Notifications”Select Turn on notifications in the banner on Fleet or in the command palette. The phone then gets a notification when an agent needs input, even when mocante is closed. When mocante is open on the phone, the notification comes from the app instead, unless you are already looking at that tab.
If the hub is a Mac with On-device lines in phone notifications on (Settings, under Hub), the notification says what the agent wants in one short line, written by the model on the hub’s Mac, so no model elsewhere reads your terminal. The notification then waits up to about four seconds for that line, and comes with the agent’s own text if no line arrives in time. It does not come at all if you answered the agent in those seconds.
When mocante is in the background or the phone is locked, the phone is offline to the hub, so the notification arrives at once. If the network drops while mocante is open, a notification can take up to about 15 seconds to arrive.