Run Coding Agents on a Server, Check from Your Phone

Where to run the agent

A coding agent like Claude Code or OpenCode needs a machine that stays on all the time. You do not need a powerful or expensive computer. The agent itself is light because the heavy work happens over an API. A small cloud server with 2 CPU cores and 4 GB of memory costs about 5 USD per month. You can also use a used mini PC, a Raspberry Pi, or even an old laptop.

Pick a Linux system you know. Ubuntu 24.04 LTS is a good choice because it is stable and well supported. Install Python, Git, and the agent software. The agent will ask for an API key. To get the key, open a browser on your laptop, log in to the agent’s website, and copy the key. Then paste it into the terminal on the server.

Start the agent once to check it works. Run a simple command like ./agent --version. The agent should print its version number. Then close the SSH session. The agent should keep running. If it stops, you need a way to keep it alive. A tool like systemd or tmux can help. For example, create a systemd service file:

[Unit]
Description=Coding Agent
After=network.target

[Service]
User=agentuser
WorkingDirectory=/home/agentuser/agent
ExecStart=/usr/bin/python3 /home/agentuser/agent/agent.py
Restart=always

[Install]
WantedBy=multi-user.target

Save the file as /etc/systemd/system/agent.service. Then run:

sudo systemctl daemon-reload
sudo systemctl enable agent
sudo systemctl start agent

Now the agent will start automatically when the server boots. It will also restart if it crashes.

The phone problem

A phone is not a laptop. It has limits that make SSH hard to use.

• The screen locks after a few minutes. When the screen locks, Android may freeze or kill background apps.
• The network changes often. It switches from wifi to mobile data, or from one wifi network to another. Each switch can break the connection.
• The app freezes when it goes to the background. Android does this to save battery. A plain SSH client loses the session when this happens.

The usual fix is tmux. Install it on the server. Start a tmux session. Run the agent inside it. If the connection drops, tmux keeps the process alive. When you reconnect, tmux attaches you back. But tmux has problems:

• You must install it on every server you use. If you forget, the session dies.
• You must remember to start a session. If you run the agent without tmux, it stops when the connection drops.
• tmux has its own commands. You must learn them to use it well.

Keep the session alive without tmux

A small helper program can do what tmux does, but without setup. The helper is called termphin-agent. It is a Rust program, about 490 KB for Linux arm64 and 540 KB for Linux x86_64. You upload it to the server over SSH. It runs in the background and keeps the shell alive.

Here is how it works:

1. You start an SSH session from your phone.
2. The app uploads the helper to the server. It puts the helper in ~/.termphin/agent.
3. The helper starts a new shell. The shell runs inside the helper.
4. If the connection drops, the helper holds the session. It keeps the shell alive.
5. When you reconnect, the helper reattaches you to the same shell. The screen state, cursor position, and scrollback are all there.

The helper is optional. Without it, the app works as a plain SSH client. But with it, you do not need tmux.

There are failure cases. The helper can crash or be killed. If the server runs out of memory, the Linux kernel may kill the helper. If the server reboots, the helper stops. To handle these cases, the app checks if the helper is running when you reconnect. If the helper is not running, the app starts a new session.

What a coding agent needs from a terminal

A coding agent shows diffs, spinners, progress bars, and full-screen text interfaces. A plain SSH client often gets these wrong. The terminal must render:

• Box-drawing characters. These are used for tables, menus, and borders.
• Colours. These are used for syntax highlighting, diffs, and status messages.
• Cursor movement. This is used for spinners, progress bars, and interactive prompts.

If the terminal does not render these correctly, the output looks broken. For example, a diff may show as a wall of text instead of aligned lines. A spinner may jump around instead of spinning smoothly.

Termphin uses a real native terminal engine. It is drawn by Flutter, not a browser. The engine is a fork of the Dart package xterm version 4.0.0. It is open source under the MIT license. This means full-screen text user interface programs render correctly.

Read a diff on a small screen

A diff can be long. On a phone, you scroll. But the terminal must keep the lines aligned. If the rendering is wrong, the diff is unreadable.

Here is an example of a diff that works:

--- old_file.txt
+++ new_file.txt
@@ -1,5 +1,5 @@
 Line 1
-Line 2
+Line 2 updated
 Line 3
 Line 4
 Line 5

The - and + signs must line up. The colours must be clear. The font must be readable at small sizes.

To make diffs readable on a phone:

• Pick a font like Fira Code or JetBrains Mono. These fonts have clear shapes and good spacing.
• Adjust the line height. A value of 1.2 to 1.4 works well.
• Adjust the padding. A value of 4 to 8 pixels keeps the text away from the edges.
• Use a colour scheme that works in daylight and at night. For example, Solarized Dark or Gruvbox.

If the diff is still hard to read, zoom in. The app lets you pinch to zoom. You can also change the font size in the settings.

Answer an agent prompt that needs a key press

Some agents ask for a key press to continue. For example:

The agent is ready. Press Enter to proceed.

On a phone, you do not have a physical keyboard. A toolbar with special keys helps. The toolbar has keys like Esc, Tab, Ctrl, and the arrow keys. You can tap these keys instead of typing them.

The toolbar is customizable. You can save different layouts for different tasks. For example:

• A layout for coding agents. It has Esc, Tab, Ctrl, and the arrow keys.
• A layout for plain SSH. It has Page Up, Page Down, and function keys.

To create a layout:

1. Open the toolbar settings.
2. Tap the + button to add a new layout.
3. Drag keys from the palette to the toolbar.
4. Save the layout.

The toolbar can float or dock. In portrait mode, it floats. In landscape mode, it docks to the side.

Send a file from the phone into the agent

An agent may ask for a file. For example:

Upload the config file to /home/user/config.yaml

On a phone, you pick the file from the file browser. The app uploads it to the server and inserts the path into the prompt.

The file browser is built in. It works like a local file manager. You can:

• Walk the server’s filesystem.
• Preview images, text files, and code.
• Open files in a syntax-highlighted editor.
• Upload files from your phone to the server.
• Download files from the server to your phone.

To upload a file:

1. Open the file browser from the app.
2. Navigate to the folder where you want to upload the file.
3. Tap the + button and select Upload.
4. Pick a file from your phone.
5. The app uploads the file and shows the path.

The editor supports syntax highlighting for many languages. It also has line numbers and basic formatting. You can edit a file and save it back to the server.

Run the same saved command on several machines

You may run the same agent on several servers. Instead of typing the command each time, save it as a snippet. A snippet is a saved command with a name. You can run it on any machine with one tap.

For example, save a snippet called start_agent:

cd ~/agent && ./agent.py --config config.yaml

To run the snippet:

1. Open the snippets menu.
2. Tap the snippet name.
3. The app pastes the command into the terminal and runs it.

The app remembers the run history. It shows the exit code and the time. If the command fails, you can see why.

You can also edit or delete snippets. For example, change the config file path or add a new flag.

Reach a dev server the agent started through a tunnel

An agent may start a dev server on a random port. For example, a web server on port 3000. To reach it from your phone, set up a tunnel. The tunnel forwards a local port on your phone to the server’s port.

For example, forward port 8080 on your phone to port 3000 on the server:

1. Open the profile for the server.
2. Go to the Tunnels section.
3. Tap Add Tunnel.
4. Set Local Port to 8080 and Remote Port to 3000.
5. Save the profile.
6. Connect to the server. The tunnel starts automatically.

Now open a browser on your phone and go to http://localhost:8080. You should see the dev server.

You can also set up tunnels on the fly. For example, if the agent starts a server on port 4000, create a new tunnel without editing the profile.

Safety rules for letting an agent run while nobody is watching

An agent runs code. It can make mistakes. Set limits to reduce risks.

• Use a dedicated user account. Do not run the agent as root. Create a user like agentuser and run the agent under that account.
• Set a memory limit. For example, 2 GB. Use systemd or cgroups to enforce the limit.
• Set a CPU limit. For example, 50% of one core. This prevents the agent from using all CPU.
• Use a firewall. Only allow connections from your IP. For example, use ufw:

sudo ufw allow from your.ip.address to any port 22
sudo ufw enable

• Check the logs often. The app can show the last lines of the session. You can also log the session to a file:

script -f /home/agentuser/session.log

Then run the agent inside script. The log file will record everything.

• Use SSH keys instead of passwords. The app stores keys in an encrypted vault on your phone. The vault is protected by a PIN or fingerprint.

• Verify host keys. The app checks the server’s host key before connecting. It fails closed if the key does not match. You can pin the key in the settings.

One honest option among others

I built Termphin, an SSH client for Android, to solve these problems. It is a native app, not a WebView or a browser wrapper. The terminal engine is a fork of the Dart package xterm version 4.0.0. It is open source under the MIT license. The Android app itself is not open source.

Termphin keeps sessions alive without tmux. A small helper agent runs on the server and holds the session. If the connection drops, the helper keeps the shell alive. When you reconnect, the helper reattaches you exactly where you left off. The helper is optional. Without it, the app works as a plain SSH client.

The terminal renders coding agents correctly. It handles diffs, spinners, and full-screen text interfaces. You can adjust the font, size, line height, padding, and colour scheme. The app has eight colour schemes and supports light and dark themes.

The app has a built-in SFTP file browser. You can walk the server’s filesystem, preview files, and edit them in a syntax-highlighted editor. You can upload files from your phone to the server and download files from the server to your phone.

You can save commands as snippets and run them on any machine. You can set up tunnels to reach dev servers. The app supports jump hosts, port forwarding, and keyboard-interactive auth for 2FA.

The app is free on Android today. There are no ads and no in-app purchases in this release. The iOS, Windows, macOS, and Linux clients are in the works but not released yet.

Conclusion

Running a coding agent on a server and checking it from a phone is possible. The hard part is the phone. The session must survive a locked screen, a network switch, or the app going to the background. The terminal must render diffs, spinners, and full-screen interfaces correctly. The app must let you send files, run saved commands, and reach dev servers through tunnels.

With the right setup, you can start a long job and check on it from anywhere. The agent stays alive, the terminal works, and the phone does not get in the way.