Pi Web is the native web interface of Pi Coding Agent. It does not transform Pi into another cloud agent. Instead, it reads existing Pi session files on the local machine and displays conversations, tool calls, context usage, model settings, skills, and project files in the browser.
Project address:
https://github.com/agegr/pi-web
The scenario for which it is suitable is clear: you are already using the Pi, but you don’t want to scroll through the history session in the terminal all the time, or you want to continue the same Agent task while looking at the project file.
Confirm before installation
On Windows, prepare:
- Node.js and npm;
- Pi Coding Agent that is already in normal use;
- PowerShell or Windows Terminal;
- A project directory managed by Git.
Check Node.js:
|
|
Pi Web reads by default:
|
|
If the Pi has not spawned any sessions, the web page can be launched, but the session list may be empty.
Run directly without installation
The easiest way is to use npx:
|
|
After the service is started, it will try to open the browser automatically. The default address is:
|
|
This method is suitable for first-time experience. There is no need to permanently install the command to the global npm directory.
Global installation
Frequently used can be executed:
|
|
If PowerShell prompts that pi-web cannot be found, check whether the npm global directory is in PATH:
|
|
After modifying PATH, you need to reopen the terminal.
Modify port and listening address
When used only on this machine by default, it is recommended to explicitly bind the loopback address:
|
|
Modify port:
|
|
Use in combination:
|
|
As a background service, you do not want to automatically open the browser:
|
|
Do not directly bind 0.0.0.0 and open the public network port just to access it from your mobile phone. Pi Web can read Agent sessions, project files, and model configurations, which may include source code, file paths, prompt words, and tool output.
Configure HTTP proxy
Pi Web reads standard proxy environment variables. Windows PowerShell example:
|
|
These variables only take effect within the current PowerShell session. NO_PROXY is very important, otherwise it may also be sent to the proxy when accessing the local service.
What to do if the Pi session cannot be found?
Pi Web reads JSONL sessions from ~/.pi/agent/sessions by default. If your Pi data directory is not in the default location, set:
|
|
First check if the directory actually exists:
|
|
Sessions are organized by project working directory. If the same repository has been opened from different drive letters, soft links or WSL paths, it may be recognized as different projects.
What can be managed in the web page?
Pi Web mainly provides these functions:
- Browse past Pi sessions by project;
- Continue, fork or create new branches from old messages;
- View Markdown, tool calls and contextual compression status;
- View project source code, documents, images, audio and PDF;
- Manage models, login information, API Key and model testing;
- Turn Skills on or off;
- Switch between Git Worktrees.
It reads and writes the local Pi configuration and session, not a separate copy of the cloud state. Before modifying model configuration or session branches, it is a good idea to back up the .pi directory.
What is the difference between Fork and intra-session branching?
Fork in Pi Web creates a new JSONL session file, suitable for trying another implementation route from a node while retaining the original session.
“Edit from here” creates a branch within the same session file. It’s more lightweight, but less intuitive to organize and migrate than standalone files.
If you want to compare two implementations or hand off to different Worktrees, Fork first; just to correct a prompt or go back to the previous step, use in-session branching.
Cooperate with Git Worktree
Worktree is suitable for allowing different Agent sessions to process different branches in independent working directories to avoid modifying the same file at the same time.
First create a Worktree in the main repository:
|
|
Pi Web’s sidebar can toggle recognized Worktrees and allow new sessions and file browsers to follow the corresponding directories.
After completion, first confirm that the branch content has been submitted, and then remove it:
|
|
Do not force deletion of Worktree when uncommitted modifications exist.
FAQ
The page opens but there is no history
Check that PI_CODING_AGENT_DIR, the default sessions directory, and the current Windows user are correct. Running it once as an administrator and once as an ordinary user may also produce two different sets of user directories.
Port is occupied
Change a port:
|
|
Or query occupied processes:
|
|
Model request failed
First confirm that the same model can be used in Pi CLI, and then check whether the Pi Web process inherits the proxy variables and API Key. If the web page can be opened, it only means that the local service is normal, but it does not mean that the model supplier is successfully connected.
The project file cannot be seen
The scope of the file preview is limited by the selected project directory and session working directory. Confirm that the session is indeed started from the target repository and do not enter the project through inconsistent drive letter mapping or soft links.
Secure remote access for Pi Web
Pi Web listens on 127.0.0.1 by default and does not provide its own application-level login. Because the page can operate Pi Coding Agent sessions, keep the service on loopback and enter through an SSH tunnel. Do not expose it directly to the public network just to save one step.
Preferred setup: loopback plus an SSH tunnel
Start Pi Web on the server with an explicit loopback address:
|
|
Confirm that the result is 127.0.0.1:30141, not 0.0.0.0:30141:
|
|
Create local port forwarding from the client:
|
|
Keep the SSH session open and visit http://127.0.0.1:30141 on the client. Pi Web remains bound to the server’s loopback interface, while SSH provides authentication and transport encryption.
Why not bind directly to 0.0.0.0
0.0.0.0 listens on every network interface. Even if the server is currently internal, a later change to cloud firewall rules, routing, VPN access, or port forwarding can expose it. Pi Web has no built-in login layer, so anyone who can reach the page may see sessions, project paths, and actions available to the Agent.
If a public bind was used for testing, restore 127.0.0.1 immediately, recheck the listener, and remove any temporary firewall or security-group rule.
Protection when a reverse proxy is unavoidable
Use a reverse proxy only when persistent multi-user access is required. The entry point should combine TLS, independent authentication, access logging, and source restrictions. A bare reverse_proxy 127.0.0.1:30141 is not sufficient hardening.
Validate the proxy configuration before reloading it:
|
|
Then verify that unauthenticated requests are rejected, WebSocket or long-lived connections still work, and the route can be disabled immediately if authentication fails. Do not log Pi session data, cookies, or model credentials.
Set proxy environment variables in the service process
If model requests need an HTTP proxy, set the variables in the same terminal that starts Pi Web:
|
|
If the page loads but model requests fail, check both the Pi Web server log and the proxy log. Browser proxy settings are not automatically inherited by the Node.js process on the server.
Tunnel disconnects and stale browser pages
A tab that still shows the old interface does not prove that the tunnel is alive. Send a new request:
|
|
If SSH disconnected, recreate the tunnel and then reload the page. Do not change the port, proxy, and startup arguments at the same time while troubleshooting.
Session isolation on multi-user servers
Pi sessions normally live under the current user’s ~/.pi directory. On a shared server, run Pi Web under separate operating-system accounts and inspect directory permissions:
|
|
Do not let a common service account read every user’s sessions or copy the whole directory to a shared drive. Review backups for project paths, conversation content, tokens, and other sensitive data.
Shutdown and acceptance checks
After remote access is no longer needed, stop Pi Web and the SSH tunnel, then confirm that the port has disappeared:
|
|
Acceptance means that Pi Web listens only on loopback; remote traffic enters only through SSH or an authenticated proxy; unauthenticated requests are rejected; a disconnected tunnel cannot start new actions; logs contain no credentials; and listener and authentication settings are checked again after every upgrade.
Security recommendations
Pi Web touches model configurations, agent sessions, and project files. suggestion:
- Default binding
127.0.0.1; - Do not map the port directly to the public network;
- Do not expose API Key, prompt words and private source code in screenshots;
- Back up the Pi session directory regularly;
- Check uncommitted modifications before switching or deleting Worktree;
- Confirm code and model data usage policies in company projects first.
Pi Web is more suitable for existing Pi users to improve session management. If you are just looking for an Agent that can write code, you should first run through the Pi CLI model, permissions, and basic workflow before installing the web interface.