Host Puggie yourself.

The hub that keeps your bots, chats and memory can run on your own Linux server. The app signs in to it over your home network or a private network such as Tailscale. No Puggie account, no source checkout and no build.

What you need

• A Linux computer with an x86_64 or arm64 processor, Docker Engine with the Compose plugin, or Podman with podman compose.
• About 1 GB of free memory and a little disk for chats and files. A small server or a spare mini PC is plenty.
• A phone that can reach the server on your local network, or over Tailscale. Port 8443 does not need to face the internet, and should not.

Start it

Make a folder for the compose file, fetch it, and start the hub. The image is public; it pulls without a login. The commands below use docker compose; with Podman, use podman compose.

mkdir puggie && cd puggie
curl -fsSLO https://puggie.app/compose.yml
PUGGIE_NAME="Home hub" docker compose up -d
docker compose logs hub

PUGGIE_NAME is the name the app shows for this hub. If you leave it out you get "Your hub"; you can change it later by running the command again with another name.

The first start creates the hub's certificate and prints its fingerprint, where it listens, and a setup code. Keep the log open for the next step. To get another setup code later:

docker compose exec hub puggie code

Connect your phone

1. Open Puggie, then Setup → Your hub → Use a hub on your server.
2. Enter the address from the log, for example 192.168.1.30:8443. Use the server's LAN or Tailscale address, not localhost.
3. Compare the fingerprint the app shows with the one in the log. They must match.
4. Enter the setup code. The phone signs in to the hub and can move its bots there or start new ones.

If the app cannot reach the hub, check that the server is on, that the phone is on the same network, and that curl -k https://192.168.1.30:8443/ answers from another computer. The -k is needed because the certificate is self-signed.

Updating

latest is the newest release. Pull it and recreate the container; your data stays in the puggie volume.

cd puggie
docker compose pull
docker compose up -d

If you would rather stay on one version, replace :latest in compose.yml with a release number, for example ghcr.io/makefunstuff/puggie-hub:0.67.0. The app's own update check follows the stable or test channel you choose in Settings; the hub image stays on the version you put here.

Backups

The puggie volume holds everything. Make a compressed copy with a temporary container:

docker run --rm -v puggie:/data -v "$PWD":/backup alpine \
  tar czf /backup/puggie-$(date +%F).tgz -C /data .

To restore it, stop the hub, replace the volume's contents and start it again:

docker compose down
docker run --rm -v puggie:/data -v "$PWD":/backup alpine \
  sh -c 'find /data -mindepth 1 -delete; tar xzf /backup/puggie-2026-10-14.tgz -C /data'
docker compose up -d

Keep a copy somewhere other than the server. A backup you have never restored is only a hope.

Using a local model

Puggie needs no GPU of its own, but a bot needs a model. You can run that model on the same machine as the hub, a gaming PC, or a spare box. Puggie talks to it over the OpenAI API; the model, not Puggie, decides how much memory and compute you need.

Puggie accepts plain http:// only for 127.0.0.1, localhost and [::1]. Every other address needs https://. So:

• A worker on the same computer as the model, installed "On the computer": http://127.0.0.1:8080/v1.
• A bot on the hub, a worker installed "In a container", or a bot on your phone: an HTTPS name, for example https://models.example.com/v1. In a container 127.0.0.1 is the container; on the phone it is the phone.
• The model on another machine: keep the server on loopback and put HTTPS in front, or use Tailscale Serve. Do not open the raw Ollama or llama.cpp port to the internet.

The full guide covers llama.cpp, Ollama, vLLM, LM Studio and any other OpenAI-compatible server, with launch settings for agent use, the exact steps in the app, networking, on-phone models and troubleshooting: Use a local model →

If something goes wrong

• The log has no setup code. It is printed on the first start. Run docker compose exec hub puggie code for a fresh one.
• The phone cannot connect. Use the server's LAN or Tailscale address, make sure port 8443 is reachable, and try curl -k https://SERVER:8443/ from another machine.
• Port 8443 is already in use. Change the left side of "8443:8443" in compose.yml to another port, then use that port in the app.
• The pull is denied. Pulling the published image needs no GitHub login. Check the image name for a typo; if it still fails, tell us through the beta rather than signing in.
• Permission errors on data. Keep the named volume. A bind mount can change the folder's owner, and the image runs as an unprivileged user.
• Wrong processor. The images are built for x86_64 and arm64. If Docker reports no matching manifest, update Docker and pull again.

What runs where

The hub keeps the shared record: bots, chats, memory, scheduled work and the web view. A bot can run on the hub, and you can add other computers from the app; the app installs the same worker there, on the computer or in a rootless container. That is useful for a laptop that should keep working when the hub is busy, or for a machine with a bigger model.

To add a computer by hand instead of from the app, run this on it:

curl -fsSLO https://puggie.app/worker.sh
sh worker.sh

It needs rootless Docker or Podman and puts its data in ~/pi-durable-worker. Pass another folder as the first argument if you want one. The app's Setup → Add a machine does the same thing over SSH and is the easier path.

If you have the source checkout, the developer setup is still the same: clone the repository and run docker compose up -d --build. The compose file above is the one to use on a server that only runs the published image.

Join the beta to get the app, or read the privacy note.