Deploy Pi Pocket

Deploy and Host self hosted Pi Pocket (AI/ML) on Railway

Pi Pocket is a durable, multiplayer, mobile-first web app for Pi coding agents, packaged here as a single Railway service with one persistent volume.

About Hosting Pi Pocket open-source software on Railway (self hosted Pi Pocket template)

This template runs the unmodified upstream Pi Pocket v0.29.0-beta.8 image as one Railway service, with a public HTTPS domain on port 8080 and a single volume mounted at /data.

Why Deploy Pi Pocket, the self-hosted mobile web app for Pi coding agents on Railway

Pi Pocket gives you a durable, mobile-first home for Pi sessions on infrastructure you control, using your own model provider. This is independent community packaging of TannerMidd/pi-pocket and is not affiliated with or endorsed by Earendil (Pi). It is a beta tag, so redeploy a newer image to update.

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Pi Pocket on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.

Railway vs Other Hosting Providers and VPS for Pi Pocket self hosting

Pi Pocket runs as one container with a volume, so hosts differ mainly in how much setup you do yourself.

Either route suits Pi Pocket, so choose by how much of the host you want to run yourself.

Common Use Cases for hosted Pi Pocket

• Durable sessions on the go: Start a long coding task at your desk, close the laptop, and check progress from your phone. Every model call and tool call is stored as it happens, so a restarted server can pick the work back up.
• Sharing a live session: Invite a trusted person to watch or steer one session, or give a viewer a read-only role. Anyone who can steer a session can run commands in the container, so invite only people you trust.
• Browsing from the built-in panel: Open local dev servers or documentation in the Chromium browser that runs inside the service. Give the service 1 to 2 GB of RAM so the browser has room to run.
• One volume for everything: Store the database, Pi sign-ins, and project workspace together on the single /data volume. Keep one replica, since the volume holds local state.
• Bringing your own model provider: Sign in from the Providers sheet or add an API key later. The server starts without a key, so you choose which provider you pay for.

Dependencies for Pi Pocket Docker hosted on Railway

Pi Pocket runs as one container on Railway, built from an unmodified upstream image plus a small start script.

Deployment Dependencies for Managed Pi Pocket Service (one container with a /data volume)

The template creates one service, pi-pocket, running ghcr.io/onepush-dev/pi-pocket:0.29.0-beta.8 on port 8080 with a public domain. The health check path is /. Give the service 1 to 2 GB of RAM for Chromium.

Implementation Details for Pi Pocket (unmodified Pi Pocket v0.29.0-beta.8 image plus a Railway start script that seeds the owner token)

The image is built from the unmodified upstream docker/Dockerfile at tag v0.29.0-beta.8 (commit cbb1eba), on the base image ghcr.io/onepush-dev/pi-pocket-base:0.29.0-beta.8, plus railway/start.sh. On first boot only, the start script writes /data/config.json with PI_POCKET_OWNER_TOKEN. The process runs as root, the upstream Compose default.

How does Pi Pocket compare against other tools

Pi Pocket vs the Railway template titled pi (Unrelated Pi CLI Terminal)

• Different product: The existing Railway template titled pi is an unrelated Pi CLI terminal. This listing is Pi Pocket, a separate web app.
• What Pi Pocket adds: A mobile-first web interface with durable sessions that keep running across restarts, plus invites and roles.
• Beta caveat: Pi Pocket deploys from the beta tag v0.29.0-beta.8, which is not a stable release.

Pi Pocket vs running Pi only in a CLI (Pi CLI Alternative)

• Phone access: Pi Pocket runs as a web app you can open from a phone, while a CLI session stays at a terminal.
• Durability: Pi Pocket stores each model and tool call as it happens, so a restarted server can continue a run.
• Where the CLI wins: A local CLI is lighter, needs no server, and no container memory for Chromium.

Pi Pocket with Docker vs Railway (Self-Hosted Container Alternative)

• Same image, different host: You can run the unmodified upstream image with Docker or Podman yourself, or deploy it on Railway.
• Railway setup: Railway provides the public HTTPS domain, the /data volume, and the generated owner token, so you skip writing Compose files.
• Docker control: Running Docker yourself gives full control over bind mounts, ports, and the container user.
• Memory and replicas: On either host, give the service 1 to 2 GB of RAM for Chromium and keep one replica.

Pi Pocket vs Other Hosted Pi Front Ends (General Hosted Alternatives)

• Scope: Pi Pocket is a self-hosted, mobile-first web app for Pi coding agents, running on infrastructure you control.
• Model access: Pi Pocket is bring-your-own-provider, so you sign in to a model provider or add an API key yourself.
• Access control: Anyone who can steer a session can run commands in the container as root, so invite only trusted people.
• Updates: The in-app Update Pi Pocket control does not apply to this image, so you redeploy a newer image tag instead.

How to use Pi Pocket on Railway?

1. Copy PI_POCKET_OWNER_TOKEN from the Variables tab, then open https://your-domain/login?token=PI_POCKET_OWNER_TOKEN once per browser. Use your Railway domain, not the container IP shown in the logs. The token is seeded on first boot only; later rotation is in the app.
2. Sign in to a model provider from the Providers sheet, or add ANTHROPIC_API_KEY or OPENAI_API_KEY as a variable.
3. Invite only trusted people. Anyone who can steer a session can run commands in the container as root.
4. Give the service 1 to 2 GB of RAM for Chromium.
5. Keep one replica, because the /data volume holds local state.
6. Back up the /data volume regularly.
7. Do not use the in-app Update Pi Pocket control. Redeploy a newer image tag instead.

Health check path:

/

How to self host Pi Pocket on other VPS Services (Pi Pocket self hosting guide)

Clone the Repository

Clone the upstream project at the pinned beta tag, then move into it.

git clone --branch v0.29.0-beta.8 https://github.com/TannerMidd/pi-pocket.git
cd pi-pocket

Install Dependencies

Upstream builds its container from docker/Dockerfile at the repository root, so you need Docker or Podman with Compose. Nothing else needs installing on the host.

Configure Environment Variables

Copy the example file if you want to change folders or the port. Set PI_POCKET_ACCESS=lan so the server listens on your network. Provider keys are optional; you can sign in to a model provider from the app later.

cp .env.example .env

Start the Pi Pocket Application

Build and start the container, then read the owner sign-in link from the logs. Give the container at least 1 to 2 GB of memory for Chromium.

docker compose up -d --build
docker compose logs pi-pocket | grep '/login?token='

Railway handles the HTTPS domain, the persistent volume, and the container lifecycle for you.

Pricing and License of Pi Pocket (Pi Pocket pricing)

Pi Pocket is open-source software released under the MIT license, and the upstream project is free to self-host. You do not pay Pi Pocket or its maintainers to run it.

Pi Pocket hosted vs self hosted comparison (Pricing, features, costs, and more)

Pi Pocket is free MIT-licensed software with no hosted plan in the pinned release. Your model usage is billed by your provider, and this is a beta tag.

Monthly cost of self hosting Pi Pocket on Railway

Railway bills by usage, so the monthly cost depends on RAM and CPU use, the size of the /data volume, and any other services you run.

System Requirements for Hosting Pi Pocket on a VPS

On a VPS, Pi Pocket needs Node.js 22.19 or newer, or a Docker or Podman host.

Frequently Asked Questions (FAQs)

How do I sign in?

Open /login?token=PI_POCKET_OWNER_TOKEN on your Railway domain once per browser, copying the token from the Variables tab. The deploy logs show the same path with the container IP, so swap in your Railway domain.

Do I need a model key at deploy time?

No. Pi Pocket starts without one, and you can sign in from the Providers sheet or add ANTHROPIC_API_KEY or OPENAI_API_KEY later.

Can I invite other people?

Yes, but invite only people you trust. Anyone who can steer a session can run commands in the container as root, while view-only users cannot make Pi act.

How much RAM does it need?

Give the service 1 to 2 GB, because Chromium runs in the container for the browser panel.

Does Update Pi Pocket upgrade the template?

No. That in-app control does not apply to this image, so redeploy a newer image tag instead.

Is this the same as the Railway template titled pi?

No. That listing is an unrelated Pi CLI terminal. This listing is Pi Pocket.

Is this an Earendil product?

No. This is independent community packaging of TannerMidd/pi-pocket and is not affiliated with or endorsed by Earendil (Pi).

What should I back up?

Back up the /data volume, which holds the database, Pi sign-ins, workspace, extensions, and themes.