How to use pi coding agent from your phone

pi is a minimal terminal coding agent. Its sessions run in a terminal on your machine, so a long task is easy to start and hard to check on once you leave the desk. This article covers the ways to reach a pi session from a phone or another computer.

Pontia is the tool we build.

The short answer

pi has no official remote or mobile client.

Option 1: Pontia

Pontia is a free, open-source remote control for coding agents running on your own machine. You install it once, sign in, and open app.pontia.dev on your phone. There is no VPN, port forwarding, or terminal app to set up.

Pontia keeps the native pi TUI. When you start a session from the Dashboard, Pontia launches pi in a tmux pane in the chosen project. A pi plugin reports the conversation to the Dashboard and accepts its controls. From a phone you can:

• start a pi session in a project directory and follow replies and tool output as they stream;
• send messages, queue them while pi works, or interrupt the current turn;
• edit an earlier message to branch the conversation from that point;
• change the model with /model, compact with /compact, and see estimated context usage;
• reference files with @.

The session is a real pi process, so you can also attach to it from a terminal at any time. Messages from the TUI and from the Dashboard go to the same conversation, and history stays in pi’s own session files:

tmux ls                       # Pontia sessions start with pontia_
tmux attach -t SESSION_NAME

pi keeps running on your machine with its own provider credentials and configuration. The browser and your machine set up an end-to-end encrypted session through Pontia’s relay, which only forwards ciphertext. Your machine connects out, so it needs no open inbound port.

Pontia supports Linux and macOS 11 or later, including headless servers. Beyond single sessions, Workflows run a large task as a sequence of pi sessions, each with a fresh context and explicit handoff files.

Setup

Install pi and tmux, and configure your model provider in pi (/login and /model). Then run:

curl -fsSL https://get.pontia.dev/install.sh | sh
pontia init   # pi is selected by default

pontia init installs the pi plugin, starts the Pontia service, signs you in with Google or GitHub, and registers the machine with an official relay. On a headless machine, the sign-in prints a URL and a one-time code that you can approve from your phone. When it finishes, open app.pontia.dev, pick the machine, and start a session.

The pi Agent Client reference covers custom pi commands and diagnostics. Advanced users can run their own relay instead of the official one.

Option 2: Build it yourself with SSH and tmux

You can also assemble remote access from standard tools: tmux keeps pi running, a private network makes the machine reachable, and a phone SSH client connects to it. A small pi extension can notify the phone when pi is waiting for input.

1. Make the machine reachable with Tailscale

Install Tailscale on the host and sign in:

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up
tailscale ip -4      # note the 100.x.y.z address

Install the Tailscale app on the phone and sign in with the same account. For an always-on host, disable key expiry in the admin console, because keys expire after 180 days by default.

The phone can run only one VPN at a time, so the Tailscale app turns off any other VPN or proxy app. Tailscale vs Cloudflare Tunnel covers Cloudflare Tunnel, which doesn’t use the phone’s VPN slot, and the routing conflicts between VPNs.

2. Run pi in tmux

Add the extended-keys setting from the tmux section below to ~/.tmux.conf first. Then:

tmux new -s pi
pi
# detach with Ctrl-b d

From the phone, connect and reattach:

mosh agent@100.x.y.z tmux attach -t pi

Mosh keeps the session alive when the phone switches networks or sleeps. It needs mosh on the host and a phone client that supports it. Without Mosh, use ssh -t agent@100.x.y.z tmux attach -t pi.

If tmux itself died, for example after a reboot, pi --continue in the project directory resumes the most recent session.

3. Scroll and steer from a phone keyboard

pi runs in fullscreen mode by default. It keeps the editor fixed and scrolls the transcript itself, with PageUp and PageDown, so pi’s output does not end up in tmux scrollback. Phone keyboards rarely have those keys. You have two choices:

• Switch pi to regular mode, which writes to the terminal’s normal scrollback. Set "tuiMode": "regular" in ~/.pi/agent/settings.json, or start pi with --tui-mode regular. You then scroll with tmux copy mode, Ctrl-b [.
• Stay in fullscreen mode and use a phone SSH app with an extra key row that includes PageUp and PageDown.

The keys you need most while pi works:

A message sent with Enter during a task is delivered after the current response and its tool calls finish. To remap keys, put them in ~/.pi/agent/keybindings.json and run /reload. pi’s keybindings reference lists the action names.

4. Get notified when pi is waiting

Subscribe to a long random ntfy topic in the ntfy phone app. Then save this as ~/.pi/agent/extensions/ntfy.ts. pi loads it automatically, and /reload applies changes.

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { basename } from "node:path";

const url = "https://ntfy.sh/YOUR_TOPIC";

export default function (pi: ExtensionAPI) {
  pi.on("agent_settled", async (event, ctx) => {
    if (event.aborted) return; // you pressed Escape, so you are already there
    await fetch(url, {
      method: "POST",
      headers: { Title: `pi: ${basename(ctx.cwd)}` },
      body: "Waiting for input",
    }).catch(() => {});
  });
}

Use agent_settled rather than agent_end. pi can retry, compact, or continue with queued messages after agent_end, so a notification sent there can arrive while pi is still working. Phone notifications for Codex and pi covers privacy and self-hosted ntfy.

What you end up with

You maintain each piece yourself: Tailscale on both devices, SSH keys on the phone, tmux, and the extension. On the phone you use pi’s full TUI on a small keyboard.

Option 3: Run pi on the phone itself

pi runs on Android through Termux. You install Node.js and pi with npm, then work in a folder on the phone. This suits small edits and scripts. The project files, toolchain, and builds then live on the phone, so it does not give you access to work on your main machine.

Make pi keys work inside tmux

By default, tmux can report Shift+Enter, Ctrl+Enter, and Enter as the same key, so Shift+Enter submits your prompt instead of inserting a new line. This affects you whenever you use the pi TUI inside tmux, including Pontia sessions you attach to. pi’s tmux guide recommends this ~/.tmux.conf for tmux 3.5 or newer:

set -g extended-keys on
set -g extended-keys-format csi-u

For tmux 3.2 through 3.4, use only set -g extended-keys on. The setting applies to the tmux server, so restart tmux before testing.

Remote control does not make pi safer

pi does not stop to ask for approval before each tool call. Its security guide states that pi acts with the permissions of the account that started it, and that watching the transcript does not create a security boundary. That holds for every option here. Watching from a phone lets you interrupt a run that goes wrong, but it cannot stop a single command before it runs.

If you leave pi working unattended, limit what it can reach. Use a dedicated user account, a container or VM, and short-lived credentials scoped to the task. pi’s guide to running in an isolated environment covers the options.

Related

• Get a phone notification when Codex or pi needs you
• Run coding agents on a VPS to keep pi on an always-on server
• How to use Codex CLI from your phone
• How Pontia works