How to Run Claude Code from Your Phone

Claude Code from your phone: how e dey work

This guide dey use terminal app for your phone. Claude Code dey run for VPS (virtual private server), inside tmux session wey dey remain open, and your phone dey open SSH (secure shell) connection go that session as long as you dey look am. If you close the app, the agent still dey work, because the process no ever run for the phone.

Claude Code still get Remote Control: run /remote-control inside a session to use am through the Claude mobile app or browser, while the process dey remain for the server.

Na this separation be the main design. Phone operating system dey suspend app few seconds after you switch comot from am, so any long job wey you start for phone go stop. E still dey get new network address every time you move from wifi go mobile data. Both problems dey disappear when the process dey run for server and the phone only dey show the screen.

You need four things for the server: tmux to hold the session, SSH keys to enter, mosh for network changes, and Claude Code itself. For the phone side, na one terminal app with key row wey you fit reach.

Wetin you need for the VPS

One small Ubuntu 24.04 box dey enough for the SSH and tmux parts. Claude Code need more. The official requirements as of October 2026 na Ubuntu 20.04 or newer for x64 or ARM64 processor, with 4 GB or more RAM. Claude Code also need paid Claude account (Pro, Max, Team or Enterprise), Console account wey get API access, or access through supported cloud provider like Amazon Bedrock, because the free Claude.ai plan no include am.

Set up the box with ordinary user wey get sudo, no be root. If the server new, first follow the first ten minutes for new VPS, because the SSH changes later for this guide easier after the user and firewall don dey.

sudo apt update && sudo apt install -y tmux mosh
curl -fsSL https://claude.ai/install.sh | bash
claude --version

The installer go put the binary for ~/.local/bin/claude, and claude --version go print line like 2.1.211 (Claude Code). If e print command not found, that directory never dey for your PATH: log out, log in again, then check with command -v claude. claude doctor go print installation and settings diagnostics without starting session.

Log in once now from laptop, before you depend on the phone. Run claude inside project directory and follow the login prompt. The process go ask you to open URL for browser and bring code back to the terminal, and to dey switch between two apps for phone screen fit slow. Do am once with real keyboard, and the credentials go remain for the server.

Start Claude Code inside tmux so connection wey drop no fit kill am

tmux new -s claude
cd ~/projects/api
claude

Detach with Ctrl-b and then d. tmux go print [detached (from session claude)] and hand shell back to you. Now close the app, lose signal, or put the phone for your pocket. The pane go continue to run.

tmux ls
tmux attach -t claude

tmux ls go print one line for each session, like claude: 1 windows (created Thu Jul 30 09:14:02 2026). tmux attach -t claude go put you back exactly where you stop, including the edit wey you never finish.

This one work because tmux dey run e own server process, and your shell plus Claude Code na children of that server, instead of sshd. When SSH connection end, kernel go send hangup signal, SIGHUP, to processes wey dey attached to that connection, but tmux server no dey among dem. Without tmux, the same screen lock wey drop your connection go stop Claude Code in the middle of tool call. Run Claude Code for VPS inside tmux explain the session layout more.

Run tmux for the server, never for the phone. If you type tmux inside session wey you already attach to, e go print sessions should be nested with care, unset $TMUX to force, and if you force am, you go get two prefix keys wey go dey clash.

Attach automatically for every login

Typing the attach command with touch keyboard dey tire person. Put this for the end of ~/.profile for the server:

if command -v tmux >/dev/null 2>&1 && [ -z "$TMUX" ] && [ -t 1 ]; then
  exec tmux new-session -A -s claude
fi

new-session -A -s claude go attach to the session wey dem name claude if e dey exist, and e go create am if e no dey exist. So one command handle both cases. exec go replace the login shell with tmux. This means say when you leave tmux, e go close the connection instead of leaving you for empty prompt. When you need plain shell, skip the file: ssh you@server -t "bash --noprofile".

Put am for ~/.profile, no be for ~/.bashrc. Bash dey also read ~/.bashrc for non-interactive SSH commands, but the [ -t 1 ] guard above stop this block from starting tmux during file transfer. Startup commands wey no get guard and wey print output fit break transfer protocols with errors like Received message too long. ~/.profile dey run for login shells only, and na that interactive SSH session dey use.

~/.profile na also where Ubuntu dey add ~/.local/bin to PATH. If claude dey work immediately after login but shell inside tmux talk say command not found, na this ordering cause am. So start tmux from login shell as above, instead of from script wey skip the profile.

iOS: Termius or Blink Shell

Both apps dey support SSH and mosh, and both dey store keys inside the app. The main difference na the interface.

Blink Shell dey use commands. For the prompt, type ssh you@server or mosh you@server, with the same syntax wey desktop terminal dey use. To open settings, type config. The Keys section fit create key pair for you.

Termius dey use forms. Fill in host entry, then change that host from SSH to Mosh inside the host details. Termius get its own mosh implementation and e support mosh 1.3.0 and newer, so server still need to get mosh package installed.

Generate the key inside the app for both cases. Never copy existing private key enter the phone. The app go show you the public half. Na that single line you go add to ~/.ssh/authorized_keys for the server. Per-device SSH keys and how to revoke one explain the naming and revoke step. This one matter more for phone than laptop.

Turn on the terminal app own biometric or passcode lock. If you no turn am on, anybody wey unlock the phone get open shell access to your server as long as the screen still dey awake.

Android: Termux

pkg upgrade
pkg install openssh mosh
ssh-keygen -t ed25519 -C "pixel"
cat ~/.ssh/id_ed25519.pub

Termux dey package OpenSSH and mosh for im own repository, so ssh, ssh-keygen and mosh dey work the same way dem dey work for desktop. Add the public key line wey e print to ~/.ssh/authorized_keys for the server, then connect with mosh you@server.

Android on-screen keyboard no get Esc key and no get Ctrl key, and Claude Code need both. Termux fit draw im own key row. Put one line for ~/.termux/termux.properties:

extra-keys = [['ESC','|','/','HOME','UP','END','PGUP'],['TAB','CTRL','ALT','LEFT','DOWN','RIGHT','PGDN']]

Then run termux-reload-settings and the row go show above the keyboard. The same reload go also pick up monospace TrueType font wey you drop for ~/.termux/font.ttf.

Android fit stop Termux while e dey background, and for this case you no lose anything except say you go reconnect. The session and the agent dey for the server.

Why terminal dey freeze when I leave wifi, and wetin mosh dey fix?

SSH connection na TCP (transmission control protocol) connection, and TCP connection dey identified by both addresses and both ports. If you waka comot from wifi range, phone go collect new address from mobile network, so the old connection no match anything for either end. Nothing dey announce this. Terminal just stop to respond until TCP give up, then ssh print client_loop: send disconnect: Broken pipe. To kill frozen session immediately, press Enter, then ~, then ..

mosh (mobile shell) remove this failure mode. E use SSH once to log in and start a mosh-server process, read back the UDP (user datagram protocol) port wey server pick, then close the SSH connection. After that, both sides exchange UDP datagrams authenticated with shared session key, so the session dey identified by that key, not by your address. New address just continue the session. mosh also echo wetin you type locally and repaint when server disagree, na why e remain usable for slow mobile link.

mosh dey use UDP port between 60000 and 61000, so open that range:

sudo ufw allow 60000:61000/udp
sudo ufw status

How to open ports with ufw get the remaining firewall details. If your provider get separate network firewall for control panel, add the same range there too, because ufw rule no fit affect filter wey dey in front of the machine.

Two mosh failures common. If login succeed then hang, and e show Nothing received from server on UDP port 60001., e mean say mosh-server start but client no fit reach am for that UDP port. Usually, firewall somewhere between phone and server dey block UDP for mosh range. If connection report mosh-server not found, package no dey installed for server or e no dey inside login PATH. Install am, or point to am directly with mosh --server=/usr/bin/mosh-server you@server.

If server login locale no be UTF-8, mosh-server go try the locale settings wey client supply and check again. E go refuse to run only if that one still no provide UTF-8, and report mosh-server needs a UTF-8 native locale to run.. Fix the locale for server first.

locale
sudo locale-gen en_US.UTF-8
sudo update-locale LANG=en_US.UTF-8

Both ends need UTF-8 locale, and mosh-server also apply the locale settings wey client send. If error still dey after you fix server, set LANG to UTF-8 value for the phone terminal app too, as mosh own FAQ note say mosh-client fit need.

Two things mosh no dey do. Its README state say mosh no support X forwarding or the non-interactive uses of SSH, including port forwarding, so to preview web app wey Claude Code just start, you still need plain ssh -L 8080:127.0.0.1:8080 you@server. E also synchronise only the screen wey dey visible, so e no get scrollback of its own. That second limit no cost anything here, because tmux keep the scrollback: Ctrl-b then [ enter copy mode, drag or arrow keys scroll, and q comot.

Make phone screen usable

Four lines for ~/.tmux.conf on the server dey handle most of the work:

set -g mouse on
set -g status-position top
set -g default-terminal "tmux-256color"
set -g history-limit 20000

mouse on dey turn touch drag to scroll, and tap to pane or window selection. This one replace most prefix keys wey hard to type. status-position top dey move the tmux status line comot from the bottom edge, where on-screen keyboard and suggestion bar dey cover am. default-terminal dey fix the terminal name wey tmux announce to Claude Code. Without that line, tmux go announce any name wey e build choose. The tmux 3.4 configure script start with screen, then e test screen-256color, tmux and tmux-256color for that order. If test fail, e keep the previous choice. So, build wey no fit find the tmux-256color terminfo entry go end with tmux, screen-256color or plain screen. Colours and box drawing fit then come out worse than dem suppose.

Learn four keys, and the rest go comfortable.

• Esc dey interrupt Claude for middle of response and keep the work wey e don already do. Na the key wey you want near your thumb.
• Ctrl+C dey also interrupt operation wey dey run. For idle prompt, the first press clear the input, and the second press exit Claude Code. So e dey more forceful.
• Esc twice dey clear draft prompt. For empty prompt, e open the rewind menu instead.
• For multi-line prompt, type \ then press Enter. This form work for every terminal. Shift+Enter na native feature for only small list of desktop terminals, and mobile clients no dey inside the list.

Avoid split panes. Phone wey dey portrait mode get around 40 columns width, so vertical split leave 20 columns for each pane, and every diff go wrap into unreadable noise. Use tmux windows instead: Ctrl-b c create one, and Ctrl-b n move go the next one. If second window get its own Claude Code session, the two sessions fit hand work to each other directly instead of making you copy text between windows for touchscreen. Turn the phone sideways when you need read diff properly.

How much text dey land for that screen na something wey you suppose set deliberately, because output style dey edit the system prompt behind every reply and terser one mean say you get fewer screenfuls to scroll pass for phone.

Long session for small screen na mostly context problem, so managing the Claude Code context window worth reading before you try run full day of work from train.

Lock am down: na keys only, no passwords

Your phone don hold one key wey fit enter machine wey dey edit your code and run commands. Off password authentication. Drop-in file safer pass editing sshd_config directly, because Ubuntu sshd_config dey include /etc/ssh/sshd_config.d/*.conf for top, and na the first value wey e find for one setting e go use.

sudo tee /etc/ssh/sshd_config.d/00-phone.conf >/dev/null <<'EOF'
PasswordAuthentication no
KbdInteractiveAuthentication no
PubkeyAuthentication yes
PermitRootLogin no
EOF
sudo sshd -t && sudo systemctl reload ssh

Dem dey read drop-ins according to filename order. Check sudo sshd -T for passwordauthentication no, kbdinteractiveauthentication no, pubkeyauthentication yes and permitrootlogin no; if earlier file set any of dem, na that one get precedence and you need correct am there.

sshd -t dey parse the config and e no print anything when the config valid. If you skip am, one typo fit make sshd fail when e reload. Keep your current session open, then test from second connection before you close anything. Wrong key at this point go give you Permission denied (publickey)., and because passwords don off, no fallback dey. Your provider console na the recovery path for that situation. If the test connection fail, reconnect with ssh -v and fix am while the first session still dey open, because that one error message fit mean five different faults and verbose output go show which one affect you.

Give every device its own key. If you lose the phone, you only need delete one line from ~/.ssh/authorized_keys, and your laptop go continue work. If you share one key, you go need change the key for every device wey you get.

If you move SSH go another port for Ubuntu 24.04, note say ssh.socket own the listener. systemd generator dey build that socket from the Port line for your SSH config, so you no need ListenStream override. But if you restart ssh alone, server go still listen for port 22. Put the Port line inside drop-in, allow the new port for ufw, then run sudo systemctl daemon-reload followed by sudo systemctl restart ssh.socket. Hardening SSH on a VPS cover that and the rest of the attack surface.

fail2ban for SSH no add much security after you turn passwords off, because system no fit accept guessed password at all. Wetin e add na quieter logs, so you fit notice real login attempt easily.

The stronger option na to keep SSH away from public internet. Put server behind WireGuard VPN wey you host yourself, bring the tunnel up for phone whenever you need am, and give sshd a ListenAddress only on the tunnel. mosh dey work through the tunnel because both sides use UDP. One thing to note: tunnel dey add packet overhead. If large transfers stall, lower the MTU (maximum transmission unit) for the phone's WireGuard config.

One last point about this workflow. From phone, you dey approve permission prompts on screen wey show only few diff lines at a time. That na reason to keep the guardrails, no be reason to disable dem. Check the permission mode wey your sessions start with too, because auto mode na now the built-in starting mode for interactive terminal sessions from Claude Code v2.1.283, and e dey apply file edits inside working directory without stopping to ask you. Running Claude Code safely on a VPS cover the user and directory limits wey make sense to set before touchscreen become your main way to enter.

When you reattach and something is wrong

tmux attach dey print no server running on /tmp/tmux-1000/default mean tmux no find server for that socket. Usually, server don disappear, and this nearly always mean say machine reboot. Check am with uptime. If box no reboot and pgrep tmux still dey show server, that one alone no mean say socket file don delete, because -L and -S flags allow server listen for another socket. If you start tmux with one of dem, pass the same flag to tmux attach. If socket really delete by mistake, pkill -USR1 tmux go ask server make e create am again. But tmux manual note say this go fail if any parent directory dey missing. Kernel updates from automatic security updates need reboot before dem fit take effect. But unattended-upgrades go reboot automatically only when Unattended-Upgrade::Automatic-Reboot dey enabled; the default value na false. Box wey reboot no get tmux session, so treat any Claude Code run as something wey you fit restart.

can't find session: claude different. tmux server dey run, but that name no dey there. tmux ls go show wetin dey exist.

If you attach and see plain shell prompt where Claude Code dey before, the process don end but the session never end. Check dmesg -T | tail for line like Out of memory: Killed process 4821 (claude). This confirm say out-of-memory kill happen. Check the shell scrollback above the prompt for other exit messages.

If window come back with wrong size, cut off for edge, or get unused space around am, e mean say two clients attach with different sizes. By default, tmux 3.4 go size window according to client wey get most recent activity (window-size latest). So your laptop, wey still attach at 200 columns wide, and phone wey get 40 columns go dey resize am one after another. Detach the other clients as you attach: tmux attach -d -t claude.

FAQ

I fit run Claude Code for the phone itself instead of VPS?

Terminal CLI no dey support Android or iOS. The platforms wey support am as of October 2026 na macOS, Windows, Ubuntu 20.04 or newer, Debian 10 or newer, and Alpine 3.19 or newer, with 4 GB or more RAM. Android and iOS no dey that list. Phone dey sleep apps and dey change network address often, and long agent run no fit tolerate that. Run am for server, then use phone as display.

The session go survive if I close the app or lose signal?

Yes, and two separate things dey handle am. tmux keep the process running for server, so nothing go die when connection end. mosh keep the connection itself alive when address change, so moving from wifi to mobile data no even require reconnect. With plain SSH and no tmux, dropped connection go send SIGHUP and Claude Code go stop in the middle of task.

Why mosh dey connect, then e show nothing?

If login succeed and then e hang with Nothing received from server on UDP port 60001., e mean say client no fit reach mosh-server for that UDP port. Usually, firewall dey block UDP 60000 to 61000. Add the range for ufw, and add am again for your provider network firewall, because most panels dey treat am as separate control. If mosh instead report say mosh-server no dey found, server no get the package, or its login PATH no include am: install am with sudo apt install mosh, or use mosh --server=/usr/bin/mosh-server you@server.

How I go interrupt Claude Code with keyboard wey no get Esc key?

Add one key row. Termux configure one with extra-keys inside ~/.termux/termux.properties, and Termius and Blink both ship one row wey you fit edit for settings. Esc interrupt running response and keep the work wey e don already do. Ctrl+C still interrupt, but if you press am twice for idle prompt, e go exit Claude Code. So use Esc first.

Opening SSH to internet safe enough for this?

If password authentication dey off, the only credential wey fit succeed na key wey never leave your devices. This na reasonable risk for machine wey you fit rebuild. Give every device its own key, so if phone loss, na one line for authorized_keys you go remove. If you no want answer for public port at all, put the box behind WireGuard and make sshd listen on the tunnel address.