Deploy and Host PI WEB on Railway

PI WEB is a web UI for the Pi Coding Agent. It keeps agent sessions alive in real workspaces — projects, files, interactive terminals, and long-running sessions — and reaches all of it from a browser tab, including a phone.

This template deploys it as one Railway service, behind a password, with everything it writes on a volume.

About Hosting PI WEB

PI WEB is a Node application, and hosting it well takes three things it does not do for you.

It ships no authentication. This is not an oversight and upstream is explicit about it in its own README: "It is not a sandbox, permission system, or multi-tenant platform. Do not expose it directly to the public internet without a trusted network, firewall, VPN, SSH tunnel, or authenticated reverse proxy." A Railway service has a public URL, and PI WEB's surface includes interactive terminals and read/write access to the container's filesystem. Deployed bare, it is a remotely drivable shell for anyone who finds the URL.

So this template does what upstream asks for. The image carries a Caddy reverse proxy that enforces HTTP basic auth on the UI, on every /api route, and on the WebSocket bridge that carries terminals and sessions. The password is generated for you as a Railway secret at deploy time, and the container refuses to start if it is unset or shorter than 12 characters — there is no window in which an unprotected instance is reachable. Verified on the live deploy: anonymous requests to /, /api/projects, /api/machines and the WebSocket upgrade all return 401; the same requests with the password return 200 and 101.

It needs the agent, and the tools, in the same container. A PI WEB with no agent installed is a half-product. The image installs Pi Coding Agent as PI WEB's npm peer (0.84.2, satisfying the >=0.84.0 requirement) and links its pi binary onto the path, alongside git, a compiler toolchain, Python, ripgrep and jq — the things an agent reaches for in a real repository.

Its state is all on disk. Workspaces, cloned repositories, uncommitted edits, session history, and your Pi provider login are files, not database rows. Without a volume every one of them is erased by the next redeploy. This template mounts a volume at /data and points every writable path at it: HOME, the PI WEB data directory, the Pi agent directory, and the workspace root. Verified by writing a file into a workspace, redeploying the service, and reading the same bytes back afterwards.

Resources. Measured idle at 208 MB under a 1 GB cap, so it starts on the Free (0.5 GB) and Trial (1 GB) plans. Headroom is what you will want in practice: a coding agent running npm install or a compile inside its workspace uses far more than the UI does, so give it a Hobby plan service if you intend to build anything substantial in it.

Why Deploy PI WEB on Railway?

Railway supplies exactly the pieces PI WEB's design assumes and a laptop does not: an address that does not change, a machine that stays up when your browser does not, and a disk that outlives the container.

That matters because the product's whole claim is session persistence. Verified on this template: a 25-second command started over the API with the client immediately disconnected ran to completion and wrote its output anyway, and its terminal was still listed on reconnect. Start a refactor on a desktop, close the lid, and pick it up from a phone.

Common Use Cases

A coding agent that is always on, reachable from any browser, without leaving a laptop awake.
Long-running agent work — migrations, refactors, test suites — that must not die when the tab closes or the connection drops.
A shared, password-protected dev box for repositories you want an agent working in continuously.
Driving an agent from a phone or tablet, where a terminal emulator is not a realistic option.

Dependencies for PI WEB

Pi Coding Agent 0.84.2 — included in the image, no separate install.
A model provider account — sign in from PI WEB's own auth dialog after you log in. Pi stores its credentials under /data/pi-agent, on the volume, so that login survives redeploys. There is no API-key variable to fill in on the deploy form.

Deployment Dependencies

PI WEB — MIT.
Pi Coding Agent.
Wrapper image and its source: bon5co/pi-web-railway, published as ghcr.io/bon5co/pi-web-railway and pinned by digest in this template.
A volume mounted at /data — included in the template.

Deployment Variables

Variable	Required	Purpose
`PI_WEB_PASSWORD`	yes	The basic-auth password. Generated for you as a Railway secret; the container refuses to boot without it.
`PI_WEB_USERNAME`	no	Basic-auth user. Baked into the image as `admin`; set it only if you want a different one.

Log in at the service URL with admin and the generated password, then sign in to your model provider from inside PI WEB.