From your desk
to your phone.

01 / Put both devices on your network.

Install the official Tailscale apps on Mac and iPhone. Sign both into your own tailnet, finish the VPN permissions, and check that both devices appear connected. Keep the iPhone VPN enabled.

On Mac, use either the official standalone app or Mac App Store app; install one variant. Follow Tailscale’s Mac guide. Copy your Mac’s Tailscale IP or full MagicDNS hostname for the phone profile.

Is Tailscale mandatory? MoshDeck opens an ordinary SSH connection. A reachable local network or another VPN can work, but Tailscale is the beta’s tested remote-access recipe. Each tester uses their own devices and tailnet. No public port forwarding is needed.

02 / Prepare the Mac.

In System Settings → General → Sharing, turn on Remote Login and allow your Mac user. Remote Management and Remote Apple Events are not needed. See Apple’s Remote Login guide.

Keep the Mac awake and connected while testing. A sleeping or powered-off Mac is unavailable; MoshDeck cannot wake it remotely.

In iTerm2 or Terminal, get your short username and install tmux if needed. The install command assumes Homebrew is already installed.

whoami
brew install tmux
command -v tmux
tmux new-session -A -s work

Save the username and full tmux path printed above. Leave this shell running inside work. Start persistent tools here, not in an unrelated iTerm2 tab.

03 / Authorize the phone. Verify the Mac.

Open MoshDeck and tap Unlock MoshDeck. Complete device authentication. Tap Unlock / show phone public key, then Copy public key or Share public key. Transfer that public key to your own Mac using a trusted method, such as AirDrop.

On the Mac, create the SSH folder if needed, then open the authorized-keys file:

mkdir -p ~/.ssh
chmod 700 ~/.ssh
touch ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys
nano ~/.ssh/authorized_keys

Append the phone’s complete ssh-ed25519 … public-key line on its own line. Preserve existing keys. Save with Ctrl-O, Enter, then Ctrl-X. The phone’s private key stays on the phone.

Now obtain the Mac’s host public key directly on the Mac:

cat /etc/ssh/ssh_host_ed25519_key.pub
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub

Transfer the public-key line to the phone through a trusted channel. This is a different key: it identifies the Mac to MoshDeck. The profile needs the full ssh-ed25519 … line, not just the SHA256 fingerprint. Never copy the similarly named file without .pub.

04 / Fill in the SSH profile.

Tap Connect. You should see connection progress and then your existing shell. If it fails, open troubleshooting; do not bypass host verification.

05 / Prove it’s the same session.

To see what is available, run this in a Mac terminal tab:

tmux list-sessions

Attach that tab to an existing session with tmux attach-session -t work. Replace work with the name you want to share, and use the same name in MoshDeck.

Inside the tmux shell on Mac, run:

echo $$

Run it again from the phone at that same shell prompt. The PID should match. Type echo hello from either device and confirm the output appears on both. Different terminal widths can resize or reflow the shared pane.

From another ordinary iTerm2 tab, you can attach with:

tmux attach-session -t work

Detach with Ctrl-B, then D. This removes only that client. Do not use exit for this check: it exits the shell. See the tmux getting-started guide.

Once the shell test passes, launch your usual coding CLI inside this tmux session. MoshDeck controls it as a terminal; it cannot adopt a process already running outside tmux. Don’t compare echo $$ from different panes, since each pane has its own shell.

Switch between sessions on iPhone.

1. Tap Sessions in the terminal header and choose an existing session.
2. For adjacent sessions, swipe left for next or right for previous. The drag previews the destination; release past the threshold to switch. Short drags cancel. The order matches the picker and does not wrap.
3. Check Reconnect target in the panel or terminal actions menu. A confirmed native switch saves that target for recovery and changes only the phone client; your Mac stays on its session.

For tmux’s own picker, use Open terminal picker (Ctrl-B, s) in Sessions, or choose Send Ctrl-B in the terminal actions menu and type lowercase s. Select with arrows and Enter. Use Hide Keyboard for more space.

Manual switching inside tmux does not update the saved reconnect target. At a shell prompt, tmux switch-client -t work is another manual option; tmux list-sessions shows available names. Avoid nesting tmux attach-session inside an attached tmux client.

Only one phone terminal is active. Switching does not start a second SSH connection or stop processes in the session you leave.

06 / Try a short recovery check.

1. Note the shell PID and leave a harmless draft in the composer.
2. Switch apps for 30 seconds, return, and check the terminal and draft.
3. Lock the phone for six minutes, return, unlock MoshDeck if asked, and check the same shell PID.
4. Try Wi-Fi → cellular. Record whether recovery is automatic or needs Connect.

Foreground use stays unlocked. Five minutes inactive/backgrounded requires authentication on return. Explicit Lock covers the terminal and closes SSH; your tmux session stays on the Mac.

During a known disconnect, raw input and sending are disabled. Composer drafts stay local. Recovery attaches to the existing tmux session and must not create a replacement if it is gone. Mac reboots and an exited tmux session cannot be recovered.

Use disposable commands for beta tests. Extended locks, terminal compatibility and coding-agent comfort are still being evaluated. Send useful feedback →