Remote control
/remote lets you drive pi from an Android phone with pi remote, the app in apps/android.
The phone connects straight to your computer, over your home network or, when you are out, a VPN
such as Tailscale. There is no cloud service in between. From the phone you can:
- watch a pi session that is running in a terminal on the computer, prompt it, steer it, abort it, change its model or thinking level, and answer the dialogs it opens (a tool-firewall approval, for example);
- start new sessions in a folder of your choice, with a model, thinking level and agent, and end them;
- open the sessions pi has saved, read their stats and todos, and continue them.
A linked phone can make your agent run commands on your computer, so linking is protected the way a credential is. This page states exactly how.
How it fits together
flowchart LR
subgraph phone[Android phone]
ui[pi remote screens, bundled in the app] -->|messages| native[native code: keystore key, pinned TLS, tokens]
end
subgraph computer[Computer]
host[remote host, HTTPS on port 8765] --> modules[pi-console modules]
modules --> rpc[pi --mode rpc sessions]
term[pi in a terminal, after /remote] <-->|loopback control channel| host
end
native -->|TLS, certificate pinned| host
- The remote host (
packages/web-ui/server/remote-host.ts) is a Node process that/remotestarts in the background and that every pi terminal on the computer shares. It serves pi-console's API (see Web console) over HTTPS to linked phones only, and adds linking, sign-in and terminal sharing. It keeps running after pi exits, until/remote stop. - The
remote-controlextension adds/remote. It starts the host, shows the QR code that links a phone, asks you to approve the phone, and shares the terminal's session with the host over a loopback control channel. - The app is a phone-sized pi-console. Its screens (
packages/web-ui/mobile) are bundled in the APK and render chats with pi-console's own Markdown and chat code. Networking, keys and tokens live in the app's native code, never in the page.
Linking a phone
- Build and install the app: see
apps/android/README.md. - In pi, in a terminal on the computer, run
/remote. It starts the host and shares this session. While no phone is linked, it also shows a QR code, a one-time code, the addresses the host can be reached at and the fingerprint of its certificate. The QR code is about 25 rows tall and 50 columns wide, so the panel is laid out for the terminal it is in: the QR code beside the details when the terminal is wide, above them when it is only tall, and otherwise the details alone, with the size the QR code needs. It reserves ten rows for the rest of the interface, so the QR code is shown only when it fits the remaining rows, and the size it names when it does not fit is a size that really does show the code. The details are enough to link a phone by hand. The panel follows the terminal as it is resized. Lines are measured in terminal columns, so a wide character or an emoji is never split or allowed past the edge; when a wide character does not fit the continuation indent it moves whole to the next line, keeping the rest of the word, and only a grapheme wider than the whole line is dropped.tests/remote-control-extension-smoke.tspins the three layouts and that no line is wider than the terminal. - In the app, tap Link a computer and scan the QR code. The camera app works too: the code is
a
pirc://pairlink that opens pi remote. Without a camera, choose Enter the details instead and type an address, the port and the code; the app then shows the fingerprint of the certificate it was given, which must match the one in the terminal. - The phone shows a device ID such as
ABCD-EFGH-JKMN-PQRS, and the terminal asks whether to link that phone, with its name, address and the device ID with its last group hidden (ABCD-EFGH-JKMN-····). Approve is still the first choice. Approving then asks you to type the last four characters of the device ID from the phone's screen; the host links the phone only if they match, and a wrong value rejects the request. A link request from an address outside loopback, the LAN ranges and Tailscale's range carries a warning to reject it unless you know why.
The computer is then listed in the app. Open it to see the shared terminal session (marked
Terminal), the sessions the host is running and the recent sessions on disk. /remote pair links
another phone, and /remote in another terminal shares that session too.
sequenceDiagram
participant T as Terminal (/remote)
participant H as Remote host
participant P as Phone
T->>H: create a one-time code
T-->>P: QR code: addresses, port, certificate fingerprint, code
P->>P: create a key in the Android Keystore
P->>H: code, public key, proof signed with the new key (TLS, fingerprint pinned)
H->>T: link request: name, address, device ID
P-->>P: show the same device ID
T->>H: approved by the operator
H-->>P: linked
P->>H: sign a fresh challenge to sign in
H-->>P: short-lived token
Away from home
By default the host listens on every interface and advertises each LAN and VPN address it finds:
LAN addresses first, then Tailscale's (100.64.0.0/10). Container bridges are skipped. The app
keeps them all, tries the one that worked last first and the others a quarter of a second apart,
and uses whichever answers. With Tailscale on both the computer and the phone, the same link works
at home and away. PI_REMOTE_BIND=tailscale makes the host listen on its Tailscale address only,
and PI_REMOTE_ADVERTISE adds names, such as a MagicDNS name, to the list.
Recommended binds: PI_REMOTE_BIND=tailscale when the phone uses Tailscale, home and away;
PI_REMOTE_BIND=loopback with an SSH or VPN forward of your own; the default all only when the
phones are on a LAN you trust. While the host listens on every interface it writes a WARNING:
line saying so to host.log, and the host's status carries it, which /remote status and
remote-cli.ts status show (tests/remote-host-smoke.ts pins the log line and the status; no
test runs remote-cli.ts).
A computer without a terminal session
On a headless computer, node packages/web-ui/server/remote-cli.ts manages the host, over SSH for
example: start, status, pair (shows the QR code and asks for the approval in that terminal),
devices, revoke, rename and stop. It must run as the same user as the host.
Commands
| Command | Effect |
|---|---|
/remote |
Start the host if needed and share this session; show a QR code while no phone is linked |
/remote pair |
Link a phone |
/remote status |
Addresses, certificate fingerprint, linked phones, shared sessions and recent failures |
/remote devices |
List linked phones |
/remote revoke <id or name> |
Unlink a phone after confirmation; its access ends at once |
/remote rename <id or name> <new name> |
Rename a linked phone |
/remote detach |
Stop sharing this session; the host keeps running |
/remote stop |
Stop the host and the sessions it started; every phone is disconnected |
/remote reset |
Stop the host and replace its certificate and identity; every phone must be linked again |
A shared session stays shared across /new, /resume, /fork and /reload in that pi process.
With PI_REMOTE_AUTO_ATTACH=1, every terminal session that starts while a host is running is
shared.
/remote works only in an interactive terminal (status and devices work anywhere). In rpc,
json and print mode, which includes every session a phone starts, it refuses to link phones or
share sessions, so a phone cannot link another phone.
Driving a terminal session from the phone
- A prompt sent while pi is idle starts a turn. While pi is working, the phone offers After this run (queued as a follow-up) and Steer now.
- A prompt that starts with
/must name a command that an extension, prompt template or skill registered. Built-in terminal commands such as/quitare refused with a message, and so is/remote. - Dialogs that extensions open in the terminal (select, confirm, input and editor) appear on the phone as well. Whichever side answers first wins, and the other copy closes.
- Notifications shown in the terminal reach the phone too.
/remote detach, or quitting pi, ends the phone's view of the session.
What protects it
| Threat | Control |
|---|---|
| Someone on the same network uses the host | Every /api route needs a bearer token. Tokens are issued only to a linked phone that signs a fresh, single-use challenge with its own key. |
| Linking a phone you do not hold | Linking needs the one-time code from the terminal (10 characters, about 50 bits, valid for 5 minutes; 5 wrong tries burn it; one offer at a time) and your approval at the terminal, where you type the last four characters of the device ID from the phone. The device ID is derived from the phone's public key, and the phone proves it holds the private key. |
| A leaked code claimed by two phones | A second correct claim of a code that is already claimed cancels the waiting request, is refused with offer_contested, is audited as pair_second_claim and is reported at the terminal; /remote pair makes a new code. |
| An agent or script approving a phone | The control secret admits any process of your account, so the host also checks who is deciding: it finds the process behind the control connection and accepts an approval only from one that has a controlling terminal, is in its foreground process group and reads its input from a terminal (an interactive pi, or remote-cli.ts pair). pi runs an agent's shell commands without a controlling terminal, and the sessions pi-console and the host start read a pipe, so their approvals are refused, audited as pair_decide_refused and reported at the terminal. Each pair_approved record names the deciding process and terminal. Rejecting works from any connection. |
A device record written into devices.json |
At start the host compares devices.json with audit.jsonl. A device with no pair_approved record is suspended: it is listed (marked SUSPENDED), cannot sign in, and is reported in host.log, /remote status and /remote devices as device_unaudited until you revoke it or pair it again. |
| Not knowing which phone answered | Each dialog a phone answers (a firewall card, a confirm, a choice) is audited as phone_dialog_answer with the device, the session, the card's risk tier and the choice (typed text by length only), and the terminal shows which phone answered. |
| A machine in the middle (café Wi-Fi, a hostile router) | The host speaks TLS with its own P-256 certificate. The QR code carries the certificate's SHA-256 fingerprint, and the app pins it on every connection, whichever address it uses. The pairing proof and every sign-in signature cover the fingerprint the phone saw and the host's identity, so a relayed connection is refused. A different certificate at a known address is reported, never used. |
| A stolen token | Tokens last an hour (PI_REMOTE_TOKEN_TTL_MIN) and are held in memory on both sides; the host keeps only their hashes. A host restart ends all of them, and the app signs in again by itself. |
| A lost or stolen phone | /remote revoke deletes the phone, its tokens and its open streams at once. The phone's private key is created in the Android Keystore (StrongBox when the phone has one) and cannot be exported. The app can ask for a fingerprint, face or screen lock when it opens and again after 30 seconds in the background, and can hide itself from screenshots and the recent-apps view. Its data is excluded from backups. |
| Guessing codes or keys | Unauthenticated routes take 60 requests a minute per address. 10 failed links or sign-ins within 10 minutes block the address for 15 minutes. Failures are written to audit.jsonl and shown by /remote status. |
| Other programs on the computer | The control channel listens on loopback only and needs a 256-bit secret from control.json (mode 0600). The secret never reaches a pi session the host starts. |
| Web content inside the app | The app loads only its bundled screens, from a private origin, under a Content-Security-Policy; any other request is refused. The page has no JavaScript interface: it exchanges messages with the native code, which accepts them only from that origin, and keys and tokens never reach it. Cleartext traffic is disabled. |
| Requests that pi-console would refuse | The host applies pi-console's own rules to the API it serves: the RPC allow-list, input validation, size limits and JSON-only state changes. |
Files on the computer
The host keeps its state in ~/.pi/agent/remote-control/ (or PI_REMOTE_STATE_DIR), mode 0700.
| File | Holds |
|---|---|
identity.json |
Server id and name |
tls-key.pem, tls-cert.pem |
The certificate phones pin and its private key (0600) |
devices.json |
Linked phones: name, device ID, public key, when linked and last seen. No secrets |
control.json |
The control channel's port and secret, while the host runs (0600) |
audit.jsonl |
Links (with the address and the deciding process), sign-ins, failures, refused approvals, second claims, unaudited devices, phone answers and revocations |
host.log |
The host's log |
Settings
| Variable | Default | Purpose |
|---|---|---|
PI_REMOTE_BIND |
all |
Where the host listens: all, loopback, tailscale (the Tailscale address only) or an IP address |
PI_REMOTE_PORT |
8765 |
HTTPS port |
PI_REMOTE_NAME |
the host name | Name the app shows |
PI_REMOTE_ADVERTISE |
unset | Extra addresses or host names for the QR code, comma-separated; listed first |
PI_REMOTE_TOKEN_TTL_MIN |
60 |
Token lifetime in minutes, 5 to 1440 |
PI_REMOTE_STATE_DIR |
~/.pi/agent/remote-control |
State directory |
PI_REMOTE_AUTO_ATTACH |
unset | 1 shares each terminal session that starts while a host is running |
PI_KIT_WEBUI_ROOT |
found as for /console |
Path to packages/web-ui, where the host ships |
PI_KIT_NODE |
pi's own runtime when it is node or bun, else node on PATH |
Absolute path to the Node.js that runs the host. A compiled pi binary cannot run it, so without node /remote refuses to start the host and says so (tests/node-runtime-smoke.ts) |
Limits and residual risks
- No notifications in the background. The app receives events only while it is open. It closes a session's stream 30 seconds after going to the background and reconnects on return.
- The host listens on every interface by default. Anyone who can reach the port can try to
link or sign in, within the limits above. Narrow it with
PI_REMOTE_BINDor a firewall; the host warns while it is bound to every interface. - The terminal check is about how a request arrives, not a wall between your processes. A
process of your account that reads
control.jsonand runs itself in the foreground of a pseudo-terminal it creates can pass it. The host cannot tell whether a person is at that terminal; the typed confirmation needs the phone's screen, which such a process does not see unless it also controls the phone. The firewall treats readingcontrol.jsonortls-key.pem, or the state directory recursively, as a credential read and writing any file there as high (tests/firewall-autoload-smoke.ts), but a process that does not go through a tool call is not seen by it. The check reads/procon Linux and useslsofandpson macOS, where it is untested; elsewhere every approval is refused. - Suspension catches a device added without a pairing record, not a forged record. Whoever can
write the state directory can write both files; the check stops a planted device that skipped
pairing, which is what an agent writing
devices.jsonwould do. - Typed-in details are trust on first use. Only the QR code (or link) carries the fingerprint. When you type the details, compare the fingerprint the app shows with the terminal's.
- The phone drives your agent with your permissions. Sessions it starts run as you, with your installed profile, so the tool firewall and its approvals apply as they do at the terminal. Anyone holding your unlocked, linked phone can do what you can do in a terminal; turn on the app lock.
- pi remote has been run on an Android 14 emulator only, not on a physical phone, and QR
decoding through a real camera has not been exercised (a
pirc://pairlink, which takes the same path after decoding, has). The current build, which targets Android 17, has only been launched on an Android 17 test image without system bars or a keyboard. It needs Android 10 or newer. - No iOS app. The host has been run on Linux only; macOS is untested and Windows is not supported.
- The app is installed from an APK you build and sign. Updates must be signed with the same key
(see
apps/android/README.md).
The Yes-first decision (SEC-5)
Decision. The pairing prompt lists Approve first, as the firewall's approval card lists Allow once first. This is an operator decision: the prompts stay quick to answer for the person who started the link. A timeout counts as a rejection.
Risk. An operator who presses Enter without reading approves. On the pairing prompt that could link a phone someone else claimed with a code they saw; on a mirrored approval card it allows a tool call.
Compensating controls, each pinned by the tests below:
- approving a phone needs the last four characters of its device ID, typed from the phone's screen (the prompt hides them), and a wrong value rejects;
- a second claim of a claimed code cancels the request and is refused (
offer_contested); - a request from outside loopback, LAN and Tailscale ranges carries a warning;
- only a person at an interactive terminal can approve (
pair_decide_refusedotherwise), and everypair_approvedrecord names the deciding process and the request's address; - a device in
devices.jsonwith nopair_approvedrecord is suspended at start; - each dialog a phone answers is audited as
phone_dialog_answerwith device, session, tier and choice, and the terminal shows which phone answered.
Not compensated: critical-tier approval cards still start on Allow once, and the Android app lock is off until you turn it on (Future work).
Tests that pin this
tests/remote-host-smoke.ts (npm run smoke:remote-host) runs the real host with a stub pi and a
protocol client that does what the app does. It checks that the state is owner-only and the
served certificate is the pinned one; that every /api route needs a token; that wrong codes burn
an offer and a proof made over another certificate burns the code; that a correct code waits for
the operator and a rejection links nothing; that challenges are single use and bound to the
certificate; that event streams are slimmed; that a pi child's dialog can be answered from the
phone; that the control secret never reaches a pi child; that a terminal session can be watched
and driven; that revoking a phone, or the phone unlinking itself, ends its token and streams at
once; that repeated failures block the address; that a wrong device-ID confirmation rejects; that
a second claim cancels the first and is refused; that an approval from a process with no
controlling terminal is refused for real, and every approval names the deciding terminal process;
that each phone answer is audited with its device and tier; and that a planted device is
suspended and the all-interfaces bind warns.
tests/remote-pairing-controls-smoke.ts (npm run smoke:remote-pairing-controls) pins the
/proc parsing, the terminal judgement, the address scopes, the confirmation, the contest, the
suspension and the phone-answer record as units. The smokes treat only the test process as an
interactive terminal, through tests/remote-terminal-preload.ts, which the smokes load into the
host process to set a hook there; the host's own code never reads the preload's variable.
tests/remote-control-extension-smoke.ts (npm run smoke:remote-control) loads the extension
against the real host. It checks that nothing opens until /remote; that a phone is linked only
after the terminal approves it and types the last four characters of its device ID, which the
prompt hides, with Approve still first; that a phone's answer to a dialog is attributed at the
terminal and audited; that history and live events reach the phone; that
prompts, steering, abort, model and thinking changes work from the phone and /remote does not;
that an answer on either side closes the other copy of a dialog; and that rpc mode cannot link
phones or share sessions.
Both run in npm run test:security and npm run check:all. Nothing in this repository tests the
Android app automatically; it was exercised by hand on an emulator against a real host.