Run Claude Code From Your Phone: The tmux + SSH Setup

Tested with: tmux 3.2a on Ubuntu 22.04, Claude Code (latest stable as of 2026-05), Termius on iOS, Tailscale 1.x, an SSH server on both a home Linux box and a small cloud VPS.

Reading time: 14 min.

Here is the situation I kept running into. I would kick off a real task in Claude Code - a refactor, a test run, a long build - and then I would need to leave my desk. Close the laptop and the session dies. Walk to another room and the work stops. The agent is perfectly happy to keep going for twenty minutes on its own, but only if the terminal it lives in stays alive.

tmux fixes exactly that. And once you pair tmux with SSH and a terminal app on your phone, you get something genuinely useful: start Claude Code at your desk, check on it from your iPhone on the couch, approve a change from your iPad at the coffee shop, and never lose the thread. This post is the full setup, start to finish. It takes about 20 to 30 minutes the first time, and then it is just there.

Wait, what about Claude Code Remote Control?

Fair question, and worth answering before you spend half an hour on this. In February 2026 Anthropic shipped an official feature called Remote Control. You run /rc inside an active Claude Code session, it shows a QR code, you scan it with the Claude mobile app, and you can watch and steer that session from your phone. It is clean and it takes about five seconds.

If all you want is to monitor a task you already started and tap approve, Remote Control is the easy answer and you should use it. But it has real limits, at least in the version I have used:

So the honest take: Remote Control is a great remote viewer, and the tmux route is a real remote terminal. I use both. The rest of this post is the tmux route, because that is the part that takes setup and the part that keeps working when you want to actually start work from your phone, not just supervise it. Remote Control is also still labelled a research preview, so check the current docs at code.claude.com for what your plan includes today.

The mental model: three layers

Before any commands, it helps to see what the pieces do, because people often install one and wonder why it does not solve the whole problem. There are three layers, and each fixes a different failure.

The first layer is the session that survives. That is tmux. tmux ("terminal multiplexer") runs your shell inside a session that lives on the server, independent of whoever is connected to it. You can detach, disconnect entirely, and the session - and Claude Code running inside it - keeps going. Reconnect later and you are back exactly where you left off.

The second layer is the secure connection. That is SSH. It is how your phone reaches a shell on the machine in the first place.

The third layer is a way to reach the machine at all from outside your home network. If the machine is a cloud VPS it already has a public address. If it is a box at home, you need something like Tailscale to reach it without exposing it to the open internet.

There is an optional fourth layer, connection resilience (mosh), and I will get to why it is worth adding at the end. The key thing to hold onto: tmux protects the session, and the connection layer protects the link. They are not the same job. You want tmux no matter what, because even a perfect connection drops when your phone sleeps - and tmux is what makes that drop a non-event.

What you need

A short checklist before you start:

• A machine to run Claude Code on. Either a computer you leave on at home (a Mac, a Linux box, a spare laptop) or a small cloud VPS. The $5-per-month tier from most providers is enough; 4 GB of RAM is comfortable.
• Claude Code installed on that machine and signed in.
• tmux installed on that machine (one command, below).
• An SSH client on your phone or tablet. This guide uses Termius, which is free and runs on iOS, iPadOS, and Android.
• A network path: Tailscale for a home machine, or the public IP for a VPS.

Step 1: Install tmux and learn the six commands that matter

tmux has a deep feature set - panes, windows, plugins, scripting. You can ignore almost all of it. For this workflow you need six commands. Install it first.

On a Linux host:

sudo apt update && sudo apt install -y tmux

On a Mac, with Homebrew:

brew install tmux

Now the six commands. Start a new named session:

tmux new -s claude

You are now inside a tmux session called claude. Run things in here as normal - this is where you will start Claude Code. To leave the session running and step out of it, press Ctrl-b, release, then press d (for "detach"). You are back at your normal shell; the session is still alive behind you.

List what is running:

$ tmux ls
claude: 1 windows (created Mon May 25 22:43:52 2026)
myapp-dev: 1 windows (created Mon May 25 22:43:52 2026)
myapp-logs: 1 windows (created Mon May 25 22:43:52 2026)

Re-attach to a session by name:

tmux attach -t claude

And when you are truly done with a session, kill it:

tmux kill-session -t claude

That is the whole vocabulary: new -s, detach with Ctrl-b d, ls, attach -t, kill-session -t. One quirk to note now so it does not trip you later: the attach flag is -t (for "target"), not -s. It reads oddly the first few times.

One config line you must not skip

By default, tmux does not handle touch scrolling, so on a phone you cannot scroll back through output - you just see the last screen. The fix is one line in a config file. Create ~/.tmux.conf on the host with this:

# ~/.tmux.conf - a minimal config that makes tmux usable from a phone
set -g mouse on
set -g history-limit 50000
set -g base-index 1
setw -g pane-base-index 1
set -sg escape-time 10

mouse on is the important one - it gives you finger scrolling. The history line keeps a long scrollback so you can read what Claude did. The base-index lines make windows start at 1, which is easier to reach on a phone keyboard, and the escape-time line keeps editors snappy over a remote link. Apply it without restarting:

tmux source-file ~/.tmux.conf

Step 2: Get the SSH server ready

Your phone connects over SSH, so the host needs an SSH server running and locked to key-based login.

On a Linux host, install and enable it:

sudo apt install -y openssh-server
sudo systemctl enable --now ssh

On a Mac, there is nothing to install. Open System Settings, go to General, then Sharing, and turn on Remote Login. That screen also shows you the exact ssh command and the username to use.

Next, use key authentication instead of a password. On the device you normally work from, generate a key if you do not have one:

ssh-keygen -t ed25519 -C "claude-code-remote"

You will copy this key onto your phone's SSH client in Step 4 - Termius can also generate its own key and push it to the host, which is the path I will use. Either way, once key login works, turn password login off on the host. Edit /etc/ssh/sshd_config and set:

PasswordAuthentication no

Then restart the service. One gotcha that cost me ten minutes: on Ubuntu 24.04 the service is named ssh, not sshd.

sudo systemctl restart ssh

Always test a new key-based login in a second terminal before you close your current session. Locking yourself out of a remote machine is a bad afternoon.

Step 3: Pick how your phone reaches the machine

This is the step that genuinely differs depending on where Claude Code runs. There are two clean paths. Pick the one that matches your setup.

Path A: Tailscale, for a machine at home

If Claude Code runs on a computer at home, do not port-forward SSH to the open internet. It works, but it puts your home machine in front of every bot on the planet. Use Tailscale instead. It builds a small private network between your devices, and they can reach each other from anywhere with no port forwarding and no firewall holes.

Install Tailscale on the host and bring it up:

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

Install the Tailscale app on your phone and sign in with the same account. Now both devices are on your private "tailnet". Tailscale gives every device a stable name through a feature called MagicDNS - something like my-macbook.tail9c2f.ts.net. Open the Tailscale app, tap your host machine, and copy that name. That is the address your phone will SSH to, and it works the same on home Wi-Fi or on cellular halfway across town.

Path B: Direct SSH, for a cloud VPS

If Claude Code runs on a VPS, it already has a public IP address and a DNS name, so your phone can SSH straight to it. The catch: a public SSH port gets brute-forced constantly, so hardening is not optional here. Three quick steps.

Install fail2ban, which watches for repeated failed logins and bans the source:

sudo apt install -y fail2ban

Turn on the firewall and allow only SSH:

sudo ufw allow 22
sudo ufw enable

And make sure password login is off, as covered in Step 2 - on a public box, key-only authentication is the difference between "fine" and "compromised". With those three done (fail2ban, firewall, keys only) a small VPS is reasonable to expose. If you ever want to be stricter, you can put the VPS on Tailscale too and close port 22 entirely, but for most people the hardened-public setup is fine.

One VPS-specific snag: if you install Claude Code fresh on a headless server, the first sign-in wants to open a browser the server does not have. The simplest fix is to forward the login port from a machine that does have a browser, run the sign-in once, and you are set:

ssh -L 15735:localhost:15735 user@your-vps-ip

Then run claude on the VPS and complete the login in your local browser. After the first sign-in this is no longer needed.

Step 4: Set up Termius on your phone

Termius is the SSH client I would point most people to first. It is free for what you need here, the interface is built for thumbs rather than ported from a desktop, and it runs on iPhone, iPad, and Android, so one setup covers every device.

Install Termius from the App Store or Play Store. You do not need to create an account - you can skip straight past it. Then:

1. Create a new Host.
2. For the address, use your Tailscale MagicDNS name (Path A) or your VPS IP or DNS name (Path B).
3. Give it a label you will recognise, like "claude box".
4. Set the username - your account name on the host, or root on a VPS if that is how it was provisioned.
5. Open the Keychain, generate a new key, then long-press it and export it to your host. That copies the public key to the server so you can log in without a password.
6. Tap the host to connect, and accept the host fingerprint the first time.

You should land at a shell prompt on the host. That is the connection working. Two notes on alternatives: on iPhone and iPad, Blink Shell is the enthusiast pick - it is a paid app with excellent Mosh support built in, and it is worth it if you live in this workflow. On Android, Termux gives you a full Linux environment rather than just a client. Termius is the easiest starting point for all of them.

Step 5: The reconnect workflow

Now the part that makes the whole thing worth it. Here is the loop you will actually run.

At your desk, or on the first connection from your phone, SSH in and either create or attach to your session:

# first time
tmux new -s claude

# every time after that
tmux attach -t claude

Inside that session, start Claude Code:

claude

Give it a task. When you want to step away, you do not quit anything. You detach: Ctrl-b then d. (In Termius, Ctrl is a dedicated key on the row above the keyboard.) Claude Code keeps running on the server.

Now your phone can do whatever it likes. Lock the screen. Drop off Wi-Fi onto cellular. Go through a tunnel. Close Termius entirely. None of it touches the session, because the session is not on your phone - it is on the host. When you want back in, open Termius, connect, and run tmux attach -t claude. You are looking at the live session again, output and all.

If you ever forget what you named things, tmux ls lists every session. That five-second habit - always work inside a named tmux session, never run claude bare - is the single thing that turns "I lost my work when the train went underground" into "I reattached and kept going".

Step 6: Add mosh so the connection itself stops dropping

With Step 5 you already have a setup that survives anything, because tmux protects the session. But there is still a small annoyance: plain SSH drops when your phone sleeps or switches networks, so each time you come back you have to reconnect the SSH session first, then attach to tmux. It works, it is just two steps and an occasional hang while a dead connection times out.

mosh ("mobile shell") removes that friction. It is a connection layer that survives IP address changes and long idle periods - you can sleep your phone for an hour, wake it on a different network, and the mosh session is simply still there. Pair it with tmux and the experience gets smooth: mosh keeps the link, tmux keeps the session.

Install mosh on the host:

sudo apt install -y mosh

mosh uses UDP, not TCP, on ports 60000 to 61000. On a VPS, open that range in the firewall:

sudo ufw allow 60000:61000/udp

On Tailscale, that traffic already flows over your tailnet, so there is nothing extra to open. In Termius, switch the host to use Mosh in its settings (Blink Shell has Mosh support too). To be clear, mosh does not replace tmux - if mosh ever does die, only tmux brings your session back. mosh is the comfort upgrade; tmux is the load-bearing part.

Step 7: Teach Claude Code to use tmux

One last piece, and it is the one that turns this from "I can watch Claude Code" into "Claude Code works well in this environment". Left alone, Claude Code will sometimes start a dev server or a file watcher in the foreground, which blocks the session and leaves you unable to do anything else from your phone.

The fix is to tell it not to. Claude Code reads a CLAUDE.md file as standing instructions, so add a section like this to the one in your project (or your home directory for a global rule):

## Long-running processes

You have tmux available on this machine. For any command that starts a
long-running process - a dev server, a file watcher, a test runner in
watch mode - always start it in its own named tmux session rather than
running it in the foreground.

Name sessions after the project and purpose, for example `myapp-dev`
and `myapp-logs`. Do not run these in the current session; they will
block it, and I won't be able to attach to them from another device.

With that in place, Claude Code spins up myapp-dev for the server and keeps working in the main session. From your phone you can tmux ls, see every process it started, and tmux attach -t myapp-dev to check the server logs - all without interrupting the agent. That is the difference between supervising one terminal and actually running a project remotely.

Gotchas worth knowing before you rely on this

A few things that will save you a confused minute:

• Cannot scroll on your phone? You skipped set -g mouse on in ~/.tmux.conf. Add it and run tmux source-file ~/.tmux.conf.
• "sshd not found" restarting SSH? On recent Ubuntu the service is ssh, not sshd.
• Attach fails with "no such session"? Run tmux ls and check the exact name. The attach flag is -t, not -s.
• Claude Code login stuck on a headless VPS? Use the ssh -L port-forward trick from Step 3, or set ANTHROPIC_API_KEY in the environment.
• Long Claude Code sessions feel heavy? They can use real memory. Check with htop and restart Claude periodically on a small VPS.

Takeaways

The whole setup comes down to a few ideas worth keeping:

• Always run Claude Code inside a named tmux session. This one habit is what makes a dropped connection a non-event instead of lost work.
• tmux protects the session; the network layer protects the link. They are separate jobs - you want tmux regardless of how good your connection is.
• Match the network path to where the machine lives: Tailscale for a home box (no port forwarding), hardened direct SSH for a VPS (fail2ban, firewall, keys only).
• Add mosh for comfort, not safety. It makes reconnecting seamless, but tmux is still the part doing the real work.
• Use Remote Control and the tmux route together. Remote Control to glance and approve, the tmux setup when you want a full terminal and the freedom to start work from anywhere.

A natural next step from here is notifications: Claude Code's hook system can ping your phone through a service like ntfy or Pushover when the agent finishes or needs a decision, so you are not checking the screen every few minutes. That is its own post, and a good one to set up once this foundation is in place.