Hand Off a Remote Mac Session to a Colleague

Recommendation first. For a two-developer team that passes work between time zones, the simplest reliable handover is a committed branch, a short status note and — if a long-running process must stay alive — a named tmux session on a host both developers are authorized to use. On Figment that host is a physical Mac rental: the i3 Mac at $49/month or an M-series Mac from $95/month, with exact chip, RAM, disk and second-user access confirmed in the quote; physical capacity is request-based. The $29 virtual Intel macOS plan runs real macOS on Linux/KVM through a browser console tied to the account owner, so it suits one developer's own builds rather than passing a live GUI between two people. Two engineers who each want their own Mac plus shared build capacity fit the Managed Mac Team plan at $999/month: two M-series Macs, two CI runners, team setup, backups, monitoring and one hour of monthly support. To size a plan or confirm shared-access arrangements, request a configuration.

Pair programming across time zones works until someone needs to hand off a build in progress. Close a viewer at the wrong moment and you lose terminal state in the GUI; skip a prep step and your colleague reconnects to a locked screen with nothing to orient from. This page is a short, honest protocol: what actually happens on disconnect, how to pass context without broadcasting credentials, and when a shared tmux session is worth the extra setup.

What actually happens when a VNC viewer disconnects

Closing a Screen Sharing or VNC viewer stops framebuffer updates to that client. The macOS user session on the host keeps running: applications stay open, background processes continue, and the desktop is left as it was. Apple's Screen Sharing user guide documents the viewer-side connect and disconnect steps and states that the host must have Screen Sharing turned on in System Settings and that the viewer supplies a user name and password. It does not describe handing off a session between users.

What can interrupt the next connection is the host's own behaviour, not the viewer:

• A locked screen — from the screensaver, the Lock Screen menu, or a "Require password after screensaver" setting — will require the account password on the next viewer connection.
• caffeinate -di keeps the display from sleeping and the system from idle-sleeping while it is running. It does not disable the screensaver, the Lock Screen command, or any password-after-sleep policy; a screen that is already locked stays locked. Treat it as a way to stop the host from going dark during a short handover window, not as a bypass for authentication.
• If each developer has their own macOS login on the host, closing the viewer does not hand the GUI from one user to the other. The desktop and the open applications belong to whichever account was signed in; a different account logs in to its own separate desktop and its own tmux server.

Terminal.app windows live inside one GUI user session. If that window is closed, or the user logs out, those shells end. That is why a long-running build often lives in a tmux session started from inside the same user's shell — not because disconnecting the viewer kills it.

A practical handover without sharing credentials

For most two-person handovers the simplest protocol is also the most reliable, and it never needs a shared password:

1. Commit or stash. git add -A && git commit -m "WIP: handover" or git stash push -m "handover-$(date +%Y%m%d-%H%M)". Push the branch. Your colleague pulls it on their own login or their own machine.
2. Move long work off the desktop. Push the artifact a reviewer actually needs — a build log, an .ipa, an .app, a test report — to your CI run, a shared artifact store or an object bucket. The colleague downloads it; they do not need your screen to inspect it.
3. Leave a written note. Three lines are enough: last action, next step, blockers. Put it in the pull request, the ticket or a shared doc, not only in a terminal buffer you cannot guarantee anyone can reach.
4. Only then consider a live session. If a process must remain running on the same host and both developers need to watch the same output, use the tmux pattern in the next section.

Do not forward your Figment browser-console URL, your Figment account credentials, or a one-time console link to anyone else. Those are tied to the account owner. For shared access to a physical Mac, agree it in the order and add the colleague through the normal macOS account and Screen Sharing permissions; keep your Figment login private.

When a shared tmux session is worth the setup

A shared tmux session helps when a build, simulator or test run must stay attached to one shell and both developers need to see the same output. The OpenBSD tmux(1) manual documents the primitives: new-session -s <name>, attach-session, attach-session -d to evict other clients, and rename-window. Tmux sockets are owned by the user who created them; by default only that user (and root) can attach. Letting a second person into the same session therefore requires one of two things: both developers sign in as the same authorized macOS account on the host, or the host owner uses tmux's server-access control to grant another local account access to the running server. Do either only when both colleagues are authorized users of the Mac — a condition to confirm on your Figment order, not a shortcut around it. Separate macOS accounts do not automatically share a GUI desktop or a tmux server.

The minimum useful pattern, run as the same macOS user:

# Outgoing developer, at the start of the work block
tmux new-session -s feature-auth

# Optional: keep the display awake during a brief handover window
caffeinate -di -t 3600 &
CAFF_PID=$!
echo "caffeinate pid is $CAFF_PID"

# Before disconnecting the viewer
tmux rename-window build
# Leave a note inside the pane as well as in the PR
printf 'last: kicked xcodebuild archive\nnext: notarize when green\nblockers: none\n' \
  | tee ~/handover.txt

# Incoming developer, after reconnecting as the same macOS account
tmux attach -d -t feature-auth
cat ~/handover.txt

# When settled, release caffeinate — only the PID you just captured
kill "$CAFF_PID"

Keep that pattern narrow. Only kill a caffeinate process you launched and whose PID you captured in the same shell; if that variable was lost, run pgrep -u "$USER" caffeinate and kill the process you recognise rather than a number copied from chat. Avoid literal <pid> placeholders in commands you actually run — angle brackets are shell redirections, not generic fill-ins.

A handover protocol card for a physical rental, printable and short:

That card is the useful artifact for this page: steps 1–3 cover almost every handover; step 4 is reserved for the cases that genuinely need a live shell on the same host.

Which Figment plan fits this workflow

Live handovers assume a physical macOS host with Screen Sharing enabled and more than one authorized user. On Figment that is the i3 Mac at $49/month or an M-series Mac from $95/month; exact chip, RAM, disk and second-user access are set in the quote, and physical capacity is request-based. For two developers who each want their own Mac plus shared CI, the Managed Mac Team plan at $999/month includes two M-series Macs, two CI runners, team setup, backups, monitoring and one hour of monthly support. The $29 virtual Intel macOS plan is accessed through a browser console bound to the account owner and is a good fit for one developer's own builds rather than for two people sharing a live GUI. To size a plan or confirm what shared authorized access looks like on your order, request a configuration.

Related: Shared remote desktop for multi-user Mac rentals · Remote Mac setup for video editing · Run GitHub Actions self-hosted runners on a Mac