Pi Web 是一个面向 Pi coding agent 的浏览器界面，主要为手机等移动端使用场景设计，也兼容桌面浏览器。它提供会话、聊天、图片输入和中英文（中文 / English）界面切换。
- Node.js 24 或更新版本（仓库
package.json要求node >=24.0.0）。 - pnpm 10（仓库固定
[email protected]）。
先在仓库根目录安装并构建。Pi runtime/session 使用统一的项目工作目录，优先级为 --cwd > PI_WEB_CWD > 服务进程 cwd。注意原始命令 PI_WEB_ACCESS_TOKEN='replace-this' pnpm --filter @pi-web/server start 会把进程 cwd 切换到 apps/server，因此通过 pnpm 启动时应显式设置目标项目目录；不要在不同目录之间混用同一组会话。
pnpm install --frozen-lockfile
pnpm build
PI_WEB_ACCESS_TOKEN='replace-this' PI_WEB_CWD='/path/to/project' pnpm --filter @pi-web/server start也可以在目标项目目录直接运行已构建的服务（此时默认使用当前目录），或传 CLI 参数：
cd /path/to/project
PI_WEB_ACCESS_TOKEN='replace-this' node /path/to/pi-web/apps/server/dist/main.js
# 等价的显式形式
PI_WEB_ACCESS_TOKEN='replace-this' node /path/to/pi-web/apps/server/dist/main.js --cwd /path/to/project默认端口为 8787。本机访问时默认使用 HTTP，不需要配置 HTTPS 证书或私钥：
PI_WEB_ACCESS_TOKEN='replace-this' PI_WEB_CWD='/path/to/project' pnpm --filter @pi-web/server start可以通过环境变量覆盖：
PI_WEB_HOST：监听 host，默认绑定127.0.0.1。PI_WEB_PORT：监听 port，默认8787。PI_WEB_ACCESS_TOKEN：访问令牌；浏览器登录后会通过 Authorization Bearer header 访问 API，令牌不会放在 URL 中。页面访问错误5次后会直接关闭程序。PI_WEB_CWD：Pi runtime、SessionManager、会话列表和页面工作区标签共同使用的项目目录。PI_WEB_WEB_DIST：可选的 Web 构建产物目录覆盖；默认根据服务端模块位置稳定解析apps/web/dist。PI_WEB_HTTPS_CERT/PI_WEB_HTTPS_KEY：可选的 HTTPS 证书和私钥路径；必须成对设置。设置后服务会直接以 HTTPS 启动。
默认 127.0.0.1 只允许本机访问。由于本项目主要面向手机等移动端使用，通常需要让手机从同一可信局域网访问运行在电脑上的 Pi Web 服务；此时必须显式设置可信局域网 host（例如受信任网卡地址），并由用户自行承担网络暴露、访问控制和 HTTPS 配置风险。不要在不可信网络上监听 0.0.0.0。
如果只需要让同一可信局域网内的设备通过 HTTP 访问，不需要 HTTPS 证书或私钥，不要设置 PI_WEB_HTTPS_CERT / PI_WEB_HTTPS_KEY：
PI_WEB_HOST=0.0.0.0 \
PI_WEB_ACCESS_TOKEN='replace-this' \
PI_WEB_CWD='/path/to/project' \
pnpm --filter @pi-web/server start然后在其他设备上访问 http://<LAN_IP>:8787。
手机浏览器访问局域网 HTTP 地址时，部分浏览器能力会受限。如果需要 HTTPS，可用本地证书让 Pi Web 直接启动，例如：
brew install mkcert
mkcert -install
mkdir -p certs
LAN_IP="$(ipconfig getifaddr en0)"
mkcert -key-file certs/pi-web-key.pem -cert-file certs/pi-web-cert.pem "$LAN_IP" localhost 127.0.0.1
PI_WEB_HOST=0.0.0.0 \
PI_WEB_ACCESS_TOKEN='replace-this' \
PI_WEB_CWD='/path/to/project' \
PI_WEB_HTTPS_CERT='certs/pi-web-cert.pem' \
PI_WEB_HTTPS_KEY='certs/pi-web-key.pem' \
pnpm --filter @pi-web/server start然后在手机上访问 https://<LAN_IP>:8787。如果手机不信任 mkcert 根证书，浏览器仍会提示证书不受信任。
真机设备测试非 MVP 验收范围：验收覆盖桌面和移动 viewport，不代表真实手机浏览器或局域网 HTTPS 配置已经完成生产验证。
pnpm check:secrets
pnpm check:docs
pnpm build
pnpm check:secretscheck:secrets 扫描 Git tracked source 和 apps/web/dist 构建产物，check:docs 验证本文档包含安全启动与验收范围说明。