---
slug: "ygncode-pi-web"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/ygncode/pi-web@main/README.md"
repo: "https://github.com/ygncode/pi-web"
source_file: "README.md"
branch: "main"
---
pi-web (Remote Control Your Pi)
[](https://github.com/ygncode/pi-web/stargazers)
[](https://www.npmjs.com/package/@ygncode/pi-web)
[](LICENSE)
[](https://t.me/+NJvFOTTa0wNjNTc9)
**English** · [Español](https://github.com/ygncode/pi-web/blob/HEAD/user-docs/readme/README.es.md) · [Français](https://github.com/ygncode/pi-web/blob/HEAD/user-docs/readme/README.fr.md) · [Deutsch](https://github.com/ygncode/pi-web/blob/HEAD/user-docs/readme/README.de.md) · [中文](https://github.com/ygncode/pi-web/blob/HEAD/user-docs/readme/README.zh.md) · [日本語](https://github.com/ygncode/pi-web/blob/HEAD/user-docs/readme/README.ja.md) · [Bahasa Indonesia](https://github.com/ygncode/pi-web/blob/HEAD/user-docs/readme/README.id.md) · [Bahasa Melayu](https://github.com/ygncode/pi-web/blob/HEAD/user-docs/readme/README.ms.md) · [Tiếng Việt](https://github.com/ygncode/pi-web/blob/HEAD/user-docs/readme/README.vi.md) · [ไทย](https://github.com/ygncode/pi-web/blob/HEAD/user-docs/readme/README.th.md) · [Filipino](https://github.com/ygncode/pi-web/blob/HEAD/user-docs/readme/README.fil.md) · [မြန်မာ](https://github.com/ygncode/pi-web/blob/HEAD/user-docs/readme/README.my.md) · [ភាសាខ្មែរ](https://github.com/ygncode/pi-web/blob/HEAD/user-docs/readme/README.km.md) · [ລາວ](https://github.com/ygncode/pi-web/blob/HEAD/user-docs/readme/README.lo.md)
Drive your [pi](https://pi.dev) coding agent from your phone, tablet, or laptop — anywhere on your network, or remotely over Tailscale.
It's a full PWA, so you can install it and use it like a native app on any device. Think of it as your own personal AI workspace — like Claude's Cowork, but with different models — chat across models, code from your phone, or turn it into a [personal assistant](https://github.com/ygncode/pi-web/blob/HEAD/user-docs/en/personal-assistant.md) that lives on your machine.
Make it yours: switch themes and fonts, and use it in your own language — pi-web ships with multiple languages and you can add your own. More features are on the way, but it won't get bloated: anything you don't need can be turned off in settings.
> [!WARNING]
> pi-web is currently in **beta**. Things will change and break!
> [!TIP]
> New here? **[Read the user guide →](https://github.com/ygncode/pi-web/blob/HEAD/user-docs/en/README.md)** for a full tour of features, install steps, and tips. ([Other languages →](https://github.com/ygncode/pi-web/blob/HEAD/user-docs/README.md))
## Screenshots
Desktop
Mobile
## How It Fits Together
```
pi (terminal) Browser (phone / tablet / laptop)
│ │
│ writes JSONL │ HTTP + SSE
▼ ▼
~/.pi/agent/sessions/ ←─── pi-web (Go HTTP server)
│
┌─────────────────┼─────────────────┐
│ │ │
pi --mode rpc fsnotify tailscale serve
(per‑session (live reload) (remote HTTPS
chat worker) via MagicDNS)
```
- **pi** writes conversation JSONL to `~/.pi/agent/sessions/` as it works.
- **pi-web** is a Go server that reads those files, renders them in the browser, and streams live updates via SSE.
- **pi --mode rpc** workers handle browser-initiated chat — one per session, reaped after 10 min idle.
- **fsnotify** watches the sessions directory so the browser reloads within milliseconds of new output.
- **Tailscale Serve** publishes the localhost server as an HTTPS endpoint on your tailnet.
## Install
```bash
pi install npm:@ygncode/pi-web@beta
```
That's it — it downloads the matching binary, sets up auto‑start, and registers the `/web`, `/pi-web`, `/remote`, and `/refresh` commands.
Once installed, open `http://127.0.0.1:31415` in your browser. From pi, use `/web` to open the current session in your browser instantly. If Tailscale is running on your machine, pi-web automatically publishes an HTTPS endpoint on your tailnet — use `/remote` from pi to get a QR code and URL for any device on your tailnet.
For manual installs, binary downloads, or building from source, see [user-docs/install.md](https://github.com/ygncode/pi-web/blob/HEAD/user-docs/en/install.md).
## Pi Integration
After `pi install npm:@ygncode/pi-web@beta`, you get:
| Command | What it does |
|---------|--------------|
| `/web` | Open the current session in your browser (SSH-aware: skips browser and shows URL only) |
| `/pi-web` | Show status, version, start/stop/restart the server, or update |
| `/remote` | Show a QR code and URL for remote access over Tailscale |
| `/refresh` | Pull new messages written from remote browsers back into the terminal session |
Session **auto-titling** is built into pi-web itself and configured on the `/settings` page. It's **on by default** and names sessions automatically. You can choose:
- **When to title** — once per session, or on every new message (the default).
- **Title model** — a free, instant **built-in word heuristic (no AI)** by default, or pick a model (e.g. a small/fast one) for smarter, model-written titles.
The package also installs the pi-web binary to `~/.pi/agent/bin/pi-web` and sets up auto-start on login.
## Auto-Start on Login
The `pi install npm:@ygncode/pi-web@beta` command sets this up automatically:
| OS | Mechanism |
|----|-----------|
| macOS | launchd plist at `~/Library/LaunchAgents/com.pi-web.plist` |
| Linux | systemd user service at `~/.config/systemd/user/pi-web.service` |
| Windows | `HKCU` Run-key entry launching a hidden starter in `~/.config/pi-web/` |
To set a token for remote access, create `~/.config/pi-web/env`:
```
PI_WEB_TOKEN=your-token-here
```
For more details (manual setup, custom ports, non-loopback binds), see [user-docs/install.md](https://github.com/ygncode/pi-web/blob/HEAD/user-docs/en/install.md).
## Development
```bash
make setup # install frontend deps and download Go modules
make check # frontend test/build + Go test/vet
make build # setup if needed, build frontend, then build ./pi-web
```