diff --git a/.changeset/sleek-agents-arrive.md b/.changeset/sleek-agents-arrive.md
new file mode 100644
index 0000000..3769ccd
--- /dev/null
+++ b/.changeset/sleek-agents-arrive.md
@@ -0,0 +1,5 @@
+---
+"@jmfederico/pi-web": patch
+---
+
+Add a static Pi Web website with installation docs, troubleshooting FAQ, and GitHub Pages deployment.
diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
new file mode 100644
index 0000000..3c277ed
--- /dev/null
+++ b/.github/workflows/pages.yml
@@ -0,0 +1,41 @@
+name: Deploy static site
+
+on:
+ push:
+ branches: [main]
+ paths:
+ - docs/**
+ - .github/workflows/pages.yml
+ workflow_dispatch:
+
+permissions:
+ contents: read
+ pages: write
+ id-token: write
+
+concurrency:
+ group: github-pages
+ cancel-in-progress: false
+
+jobs:
+ deploy:
+ name: Deploy GitHub Pages
+ runs-on: ubuntu-latest
+ environment:
+ name: github-pages
+ url: ${{ steps.deployment.outputs.page_url }}
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v5
+
+ - name: Configure Pages
+ uses: actions/configure-pages@v6
+
+ - name: Upload static site
+ uses: actions/upload-pages-artifact@v4
+ with:
+ path: docs
+
+ - name: Deploy
+ id: deployment
+ uses: actions/deploy-pages@v4
diff --git a/README.md b/README.md
index 65a9a48..3a763d5 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,8 @@
[](LICENSE)
[](https://github.com/earendil-works/pi/tree/main/packages/coding-agent)
+Website:
+
**Run AI coding agents on your own machine or server, keep them alive in real workspaces, and control everything from a browser.**
@@ -175,6 +177,8 @@ npm run dev
Open the Vite URL, usually .
+During development, the static marketing/docs site is also served by the Vite dev server at .
+
For the recommended split development setup, run these in separate terminals:
```bash
diff --git a/docs/.nojekyll b/docs/.nojekyll
new file mode 100644
index 0000000..e69de29
diff --git a/docs/faq.html b/docs/faq.html
new file mode 100644
index 0000000..83e685a
--- /dev/null
+++ b/docs/faq.html
@@ -0,0 +1,202 @@
+
+
+
+
+
+ Pi Web FAQ
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
FAQ & troubleshooting
+
Fix the things that usually go wrong first.
+
+ Most Pi Web install issues are environment issues: systemd availability, PATH setup, Node version managers,
+ or remote access expectations.
+
+
+
+
+
+
+
+
+
+
+
Is this Linux only?
+
+ No. Pi Web can run anywhere its runtime dependencies work, including macOS and Windows through WSL. The
+ automatic pi-web install command is the Linux-specific part because it writes and manages
+ systemctl --user services.
+
+
+
Linux with systemd: use npm install -g @jmfederico/pi-web and pi-web install.
+
macOS: install the package, then run pi-web-sessiond and pi-web-server manually.
+
Windows: use WSL. If your WSL distro has systemd enabled, the installer may work; otherwise use the manual run path.
+
+
Native Windows outside WSL is not the recommended path today.
+
+
+
+
Tools are failing, node is not found, or Pi cannot find commands
+
+ The shell environment needs to be set up so login shells have the required PATH entries for Pi Web, Pi,
+ and any tools your agents need. Pi Web services run commands through a non-interactive login shell, so
+ an interactive terminal can work while services fail.
+
+
+
+ Run diagnostics
+
+
+
$ pi-web doctor
+
+
+
bash: put PATH setup in ~/.bash_profile or ~/.profile. If ~/.bash_profile exists, source ~/.profile from it if needed.
+
zsh: put PATH setup in ~/.zprofile, not only ~/.zshrc.
+
fish: prefer universal PATH setup, for example fish_add_path -U ....
+
+
Avoid relying only on prompt hooks or interactive-only shell files for tools needed by services.
+
+
+
+
What does pi-web doctor check?
+
+ It checks whether the service shell and systemd user environment can find Node 22+, npm, Pi, and the Pi
+ Web binaries. It also reports whether user service lingering is enabled for server-style installs.
+
+
+ If something works in your terminal but fails in doctor, treat that as a login-shell PATH mismatch and
+ move the setup earlier in your shell startup chain.
+
+
+
+
+
I installed Node with nvm, fnm, asdf, or another version manager
+
+ Version managers often initialize in interactive shells only. Pi Web needs Node and npm to be available to
+ login shells and systemd user services.
+
+
+
Move the version manager initialization to your login shell file.
+
Make sure node --version is at least v22 from bash -lc, zsh -lc, or your detected shell.
+
Run pi-web doctor again after changing shell files.
+
+
+
+
+
systemctl --user is not available
+
+ The automatic installer needs Linux user systemd. On macOS, WSL without systemd, containers without a
+ user systemd manager, or minimal Linux environments, run the two processes manually:
+
+
+
+ Manual run
+
+
+
$ pi-web-sessiond
+# in another terminal
+$ PI_WEB_PORT=8504 pi-web-server
+
+
+
+
+
I cannot open the web UI
+
+
Check pi-web status.
+
Check logs with pi-web logs.
+
Make sure port 8504 is not already in use.
+
On a remote server, use an SSH tunnel: ssh -L 8504:127.0.0.1:8504 user@server.
+
+
+
+
+
Can I expose Pi Web to the public internet?
+
+ Do not expose it directly. Pi Web assumes trusted users and trusted server paths. Keep the default
+ localhost bind and use SSH tunneling, a VPN, or a reverse proxy with authentication and network policy.
+
+
+
+
+
Sessions stop unexpectedly
+
+ Active agent runtimes are owned by the session daemon. Browser disconnects and web/API restarts should
+ not stop them. If they stop anyway, check whether the session daemon service restarted or crashed.
+
+
+
+
+
+
+
+
diff --git a/docs/index.html b/docs/index.html
new file mode 100644
index 0000000..78e563a
--- /dev/null
+++ b/docs/index.html
@@ -0,0 +1,189 @@
+
+
+
+
+
+ Pi Web — persistent AI coding agents in your browser
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
A cockpit for agentic development
+
Your agents keep working. You just need a browser.
+
+ Pi Web runs Pi Coding Agent sessions in real server-side workspaces, keeps them alive when your browser
+ leaves, and gives you a fast web surface to supervise, redirect, and review the work.
+
+ Workspaces, sessions, transcripts, terminals — one agent control plane.
+ Bring your own repositories.
+
+
+
+
+
+
+
+
+
+
Why it feels different
+
Not another tab. A persistent place for agent work.
+
+
+
+
↻
+
Come back later
+
+ Active sessions live in a long-running daemon, not in your browser tab. Close the lid, reconnect from a
+ phone, and continue supervising the same work.
+
+
+
+
⌘
+
Use real workspaces
+
+ Add projects once, discover git worktrees automatically, and start agents where the code actually lives.
+
+
+
+
◌
+
Keep control
+
+ Watch transcript history, status, shell activity, context usage, and costs while redirecting the agent in
+ realtime.
+
+
+
+
+
+
+
+
+
+
Quick install
+
Linux servers get the smooth path.
+
+
Install the package globally with npm.
+
Run the installer to create user-level systemd services.
+
Open the local URL, or tunnel it from a remote machine.
$ npm install -g @jmfederico/pi-web
+$ pi-web install
+$ pi-web doctor
+# Open http://127.0.0.1:8504
+
+
+
+
+
+
+
+
macOS and WSL?
+
+ Pi Web itself is not Linux-only. The one-command service installer targets Linux systemd. macOS and WSL can
+ run Pi Web manually; WSL with systemd can use the installer too.
+
+ Services run login shells. If tools work in your interactive terminal but not in Pi Web, fix PATH in your
+ login shell startup files and run the doctor command.
+
+ The best production-style setup is a Linux machine with user-level systemd services. macOS and Windows WSL
+ are useful too: run the two Pi Web processes manually, or use the installer in WSL when systemd is enabled.
+
+
+
+
+
+
+
+
+
+
+
Requirements
+
+
Node.js 22 or newer and npm.
+
Pi Coding Agent installed/configured so the pi command works for your user.
+
A shell login environment that exposes Node, npm, Pi, git, and any tools your agents need.
+
For the automatic installer: Linux with systemctl --user.
+
+
+ Important PATH detail:
+ Pi Web services run through your login shell with -lc. Setup that only lives in interactive shell
+ files or prompt hooks may not be visible to services. Run pi-web doctor after installing.
+
+
+
+
+
Recommended: Linux systemd install
+
+ This creates two user services: one long-lived session daemon and one web/API service. It is the easiest
+ way to keep sessions available after SSH disconnects or browser restarts.
+
+
+
+ Linux install
+
+
+
$ npm install -g @jmfederico/pi-web
+# Recommended on servers so user services survive logout/reboot:
+$ sudo loginctl enable-linger "$USER"
+$ pi-web install
+$ pi-web doctor
If you prefer a curl pipe, use the repository installer:
+
+
+ One-liner
+
+
+
$ curl -fsSL https://raw.githubusercontent.com/jmfederico/pi-web/main/install.sh | sh
+
+
+
+
+
Install through Pi
+
Pi Web is also published as a Pi package. This exposes a /pi-web command inside Pi.
+
+
+ Pi package path
+
+
+
$ pi install npm:@jmfederico/pi-web
+
+# Then inside Pi:
+/pi-web install
+/pi-web status
+/pi-web logs
+/pi-web doctor
+
+
+
+
+
macOS / WSL manual run
+
+ Pi Web is not Linux-only, but the pi-web install service setup is Linux/systemd-specific. On macOS
+ or WSL without systemd, install the package and run the daemon and web server yourself.
+
+ On modern WSL distributions with systemd enabled, the Linux installer can work. Without systemd, use the
+ manual run approach above.
+
+
+
+
+
Remote access
+
+ Pi Web binds to 127.0.0.1:8504 by default. For a remote server, keep that safe default and use an
+ SSH tunnel:
+
+
+
+ SSH tunnel
+
+
+
$ ssh -L 8504:127.0.0.1:8504 user@your-server
+# Open http://127.0.0.1:8504 on your local machine
+
+
+ Pi Web is designed for trusted users and trusted server paths. Do not expose it directly to the public
+ internet without adding your own network controls, authentication, or reverse proxy policy.
+
+
+
+
+
Manage services
+
+
+ Useful commands
+
+
+
$ pi-web status
+$ pi-web logs
+$ pi-web restart
+$ pi-web doctor
+$ systemctl --user status pi-web-sessiond.service pi-web.service
+$ journalctl --user -u pi-web-sessiond.service -u pi-web.service -f
+
+
+
+
+
Configure
+
+ The installer writes a config file under your user config directory. The web server defaults to
+ 127.0.0.1:8504 and stores Pi Web state in ~/.pi-web.
+
+
+
PI_WEB_PORT or PORT: web server port.
+
PI_WEB_HOST: web server bind host. Keep 127.0.0.1 unless you know why not.
+
PI_WEB_DATA_DIR: data directory, default ~/.pi-web.
+
PI_WEB_SESSIOND_SOCKET: Unix socket path for daemon communication.
+
+
+
+
+
Uninstall
+
Remove the user services, then remove the npm package if you installed it globally.
+