Keep a Coding Agent Running When Your Phone Sleeps
You start Claude Code on a long refactor, lock your phone, and come back to a dead session and a half-finished job. This is the single most common reason running coding agents from a phone feels unworkable, and it is not the agent's fault. iOS aggressively suspends network connections when an app backgrounds or the screen locks, and a plain SSH session dies with them. There are three separate failure modes here, each needing a different fix. Set up all three and the problem goes away.
Written by the GateShell team at Hefty Innovations
Step by step
- 1
Know which of the three things is actually killing you
They look identical from the outside and have different solutions. First: you switch networks, from Wi-Fi to cellular or between access points, and the TCP connection underneath SSH breaks. Second: the screen locks or you switch apps, and iOS suspends the connection after a grace period. Third: iOS terminates the app outright to reclaim memory, which no client-side setting can prevent. Fixing only one leaves you with a session that still dies, just less often.
- 2
Put the work in tmux so it stops depending on your phone at all
This is the layer that matters most, because it is the only one that survives the app being terminated. tmux runs on the server: your agent keeps working inside it whether or not anything is connected. In GateShell, open the server's settings, find Auto-Reconnect & tmux, and turn on tmux Auto-Attach with a session name. Every connection then attaches to that same session automatically. Start your agent inside it and the worst case becomes a reconnect rather than a lost job.
- 3
Turn on Mosh so a network change is not an interruption
tmux protects the work; Mosh protects the session you are watching it through. Mosh authenticates over SSH and then moves to an encrypted UDP transport that is not bound to an IP address, so walking out of Wi-Fi range does not end the connection. Your server needs mosh-server installed and inbound UDP 60000-61000 open. A firewall allowing only port 22 will connect fine and then fail to roam, which is the usual cause of it not working.
- 4
Leave the Live Activity on so you can see the state without opening the app
With Live Activity enabled, an active connection appears on the Lock Screen and in the Dynamic Island. This is more useful than it sounds for agent work: a long task means long stretches where you want to know the session is alive without unlocking the phone and reopening the app, which is itself the thing that risks disturbing it.
- 5
Tell the agent to leave a trail
This one is a working habit rather than a setting. Ask your agent to commit at meaningful checkpoints, or to write progress to a file, so that if something does interrupt the session you can see exactly how far it got. Agents are generally good at this when asked and rarely do it unprompted. It turns a lost session from lost work into a resumed task.
- 6
Test it deliberately, before you need it
Start a genuinely long task, then do the things that normally break it: switch from Wi-Fi to cellular, lock the phone for several minutes, open other apps. Reconnect. With tmux auto-attach and Mosh both on, you should land back in the running session. Learning this works while nothing is at stake is much better than discovering it does not during a real job.
Frequently asked questions
Do I need both tmux and Mosh, or is one enough?+
They cover different failures, and the gap shows up at the worst time. Mosh keeps your connection alive across network changes but cannot help if iOS terminates the app entirely. tmux keeps the work running on the server regardless of what happens to the client, but without Mosh you still get a dropped connection every time you change networks. Together they cover everything short of the server itself going down.
Will the agent keep working while my phone is locked?+
Yes, if it is running inside tmux, because then it is running on your server rather than on your phone. Your phone is only a window onto it. That is the whole point of the tmux layer: the work stops depending on the state of your device.
Why does my session survive a short lock but not a long one?+
iOS gives a backgrounded app a grace period before suspending its network connections, and terminates apps entirely under memory pressure after longer periods. A short lock falls inside the grace window; a long one does not. This is exactly the boundary tmux is for: inside tmux, an app termination costs you a reconnect rather than the job.
Does this work with Codex and Gemini CLI too?+
Yes. None of these three layers know or care which agent is running. tmux, Mosh, and the Live Activity operate on the session, not on the process inside it. Anything you can start in a shell benefits equally.
What if my server does not allow UDP?+
Then Mosh cannot roam, and GateShell will tell you so and fall back to SSH rather than silently pretending. You lose network roaming but keep the tmux layer, which is the more important of the two. If you control the firewall, opening UDP 60000-61000 is worth doing.
Try it in GateShell
GateShell is a zero-backend SSH client for iPhone, iPad, and Mac, with no vendor cloud, no accounts and no telemetry. Everything above works out of the box.
Guide reflects GateShell's shipped features as of September 2026. Steps assume basic familiarity with SSH and the command line; server-side commands may vary by distribution. All product names, logos, and brands are property of their respective owners.