Deployment guide

PoB-Enhanced is one container. It needs no database, keeps its few files (your current build, saved builds and item art) in /data, and serves the web UI, the REST API and the MCP endpoint on a single port (8080). Pick the setup that matches where you want it to run.

Choose a setup

Docker Desktop (Windows and macOS)

1. Install Docker Desktop and start it. On Windows, accept the WSL 2 option when the installer asks.
2. Open a terminal (PowerShell on Windows, Terminal on macOS) and run:

   docker run -d --name pob-enhanced --restart unless-stopped -p 8080:8080 -v pob2-data:/data ghcr.io/skitty4fingers/pob-enhanced:latest

   The first start downloads the image (a few hundred MB). -v pob2-data:/data keeps your builds when the container is replaced by an update.
3. Open http://localhost:8080. Continue with First run.

Port 8080 taken? Use another host port, for example -p 8090:8080, and open http://localhost:8090.

Docker Compose

Compose keeps the settings in a file and makes updates one command.

1. Download the Compose file:

   curl -O https://raw.githubusercontent.com/Skitty4fingers/PoB-Enhanced/main/compose.image.yml

2. Optional: create a .env file next to it (see Settings), for example:

   POB2_PORT=8080
   POB2_BIND=127.0.0.1

3. Start it:

   docker compose -f compose.image.yml up -d

The Compose file listens on 127.0.0.1 by default, so only this machine can reach it, and keeps your builds in the pob2-data volume. See the next section to open it up.

Open it to your network

To use it from another PC, a tablet or your phone on the same network:

1. In .env, set POB2_BIND=0.0.0.0 (Compose only; docker run -p 8080:8080 already listens on every address).
2. Set POB2_ALLOWED_HOSTS to the names and IPs other devices will type, for example POB2_ALLOWED_HOSTS=gaming-pc,192.168.1.20. The web UI works without it; the MCP endpoint (/mcp) rejects unknown host names to block DNS-rebinding attacks.
3. Restart: docker compose -f compose.image.yml up -d, then browse to http://192.168.1.20:8080 from the other device.

TrueNAS SCALE

1. Open Apps → Discover Apps and click Custom App.
2. Application name: pob-enhanced.
3. Image: repository ghcr.io/skitty4fingers/pob-enhanced, tag latest, pull policy Always pull (so a restart picks up new versions).
4. Environment variables: add POB2_ALLOWED_HOSTS with your NAS name and IP, for example truenas,192.168.1.147.
5. Network → Ports: container port 8080, host port 8080 (or any free port), protocol TCP.
6. Storage: add a host path (for example a dataset apps/pob2) mounted at /data, so builds survive updates. Give it to user ID 1000, or use an ixVolume. Click Install.
7. When the app shows Running, open http://<nas>:8080.

To update, stop and start the app (with Always pull it fetches the newest image).

Unraid

1. Go to Docker → Add Container.
2. Name: pob-enhanced, Repository: ghcr.io/skitty4fingers/pob-enhanced:latest, Network type: Bridge.
3. Add another Path, Port, Variable… → Port: container 8080, host 8080.
4. Add another Path, Port, Variable… → Variable: key POB2_ALLOWED_HOSTS, value tower,192.168.1.30 (your server's name and IP).
5. Add another Path, Port, Variable… → Path: container /data, host /mnt/user/appdata/pob-enhanced.
6. Click Apply, then open http://<server>:8080. Update from the Docker tab with Check for updates.

Portainer or Synology Container Manager

Create a stack (Portainer: Stacks → Add stack; Synology: Container Manager → Project → Create) with this Compose file:

services:
  pob2:
    image: ghcr.io/skitty4fingers/pob-enhanced:latest
    ports:
      - "8080:8080"
    environment:
      POB2_ALLOWED_HOSTS: "nas,192.168.1.20"   # the names/IPs you browse to
    volumes:
      - pob2-data:/data                         # current build and saved builds
    restart: unless-stopped
volumes:
  pob2-data:

Deploy it and open http://<nas>:8080. To update, pull the image again and redeploy the stack.

Tailscale (private HTTPS, no open ports)

compose.tailscale.yml puts PoB-Enhanced behind a Tailscale sidecar with a real certificate. Only devices on your tailnet can reach it, at https://pob2.<tailnet>.ts.net.

1. In the Tailscale admin console, enable MagicDNS and HTTPS Certificates, and note your tailnet name (like tail1234.ts.net).
2. Create an auth key.
3. Get the code and settings:

   git clone https://github.com/Skitty4fingers/PoB-Enhanced.git
   cd PoB-Enhanced
   cp .env.example .env      # set TS_AUTHKEY and TS_TAILNET

4. Start it:

   docker compose -f compose.tailscale.yml up -d --build

5. Open https://pob2.<tailnet>.ts.net from any device on your tailnet.

Build from source

git clone https://github.com/Skitty4fingers/PoB-Enhanced.git
cd PoB-Enhanced
docker compose -f compose.enhanced.yml up -d --build

The first build takes a few minutes: it compiles LuaJIT and the web UI. To update, run git pull and the same command again.

Without Docker (Linux, macOS, WSL)

You need Python 3.10+, uv, Node 22+, git and a C compiler.

git clone https://github.com/Skitty4fingers/PoB-Enhanced.git
cd PoB-Enhanced
scripts/setup-engine.sh                  # builds LuaJIT + lua-utf8, installs Python deps, builds the web UI
export PATH="$HOME/.local/bin:$PATH"
uv run --directory python pob2-web       # http://127.0.0.1:8080

First run

1. Click Import and paste a PoB share code, a pobb.in / pastebin link, or your poe.ninja character page: https://poe.ninja/poe2/profile/<account>/<league>/character/<name>.
2. Open the Config tab and set enemy conditions, buffs and charges to how you play.
3. Open the Help tab (or the ? button) for a tour of every tool.
4. Later, press Update to re-import your character. Config settings are kept.

Connect an AI agent (MCP)

The MCP endpoint is http://localhost:8080/mcp (Streamable HTTP). The app's AI / MCP tab shows these settings filled in with your server's address. Agents share the live build with the web UI, the UI refreshes as they work, and anything they change can be undone.

On your computer

These run where you are, so they reach the server directly. From another machine, use the server's address (for example http://192.168.1.20:8080/mcp) and add that name or IP to POB2_ALLOWED_HOSTS.

claude mcp add --transport http pob2 http://localhost:8080/mcp

{
  "mcpServers": {
    "pob2": { "command": "npx", "args": ["-y", "mcp-remote", "http://localhost:8080/mcp"] }
  }
}

codex mcp add pob2 --url http://localhost:8080/mcp

[mcp_servers.pob2]
url = "http://localhost:8080/mcp"

{ "mcpServers": { "pob2": { "serverUrl": "http://localhost:8080/mcp" } } }

gemini mcp add --transport http --scope user pob2 http://localhost:8080/mcp

{ "mcpServers": { "pob2": { "url": "http://localhost:8080/mcp" } } }

{ "mcpServers": { "pob2": { "command": "docker", "args": ["run", "--rm", "-i", "ghcr.io/skitty4fingers/pob-enhanced:latest", "pob2-mcp"] } } }

Self-hosted models

Run a local model and let it drive PoB-Enhanced. Pick a model with tool calling (Qwen 3, Llama 3.1 or newer, Mistral Small...). Clients running in Docker reach the server at host.docker.internal (on Linux start them with --add-host=host.docker.internal:host-gateway); add host.docker.internal to POB2_ALLOWED_HOSTS.

{ "mcpServers": { "pob2": { "url": "http://localhost:8080/mcp" } } }

mcpServers:
  pob2:
    type: streamable-http
    url: http://host.docker.internal:8080/mcp

Cloud chat apps: ChatGPT, Grok, Gemini, Muse, Claude.ai

These connect from the provider's servers, so they need a public HTTPS address (they reject localhost and private addresses). A tunnel is the quickest way:

cloudflared tunnel --url http://localhost:8080      # Cloudflare quick tunnel, no account needed
ngrok http 8080                                    # or ngrok

Add the hostname it prints (for example word-word.trycloudflare.com) to POB2_ALLOWED_HOSTS and restart, then use https://<that-host>/mcp:

Updating

Settings

Troubleshooting

Still stuck? Open an issue with your setup and the container log (docker logs pob-enhanced).