Installation

Beta

Docker Compose

Run pwrp beside your containers. A named volume keeps login and settings.

Complete example

This example exposes Nginx. Set the tunnel's local port to 80 in the Portwarp dashboard.

compose.yaml

services:
  pwrp:
    image: ghcr.io/portwarp/cli:latest
    restart: unless-stopped
    user: "10001:10001"
    read_only: true
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    tmpfs:
      - /tmp
    volumes:
      - pwrp-data:/home/pwrp/.portwarp
    networks:
      - app-network
    stop_grace_period: 20s

  web:
    image: nginx:alpine
    restart: unless-stopped
    networks:
      - app-network

networks:
  app-network:

volumes:
  pwrp-data:

Do not publish a port for the pwrp service. Portwarp creates outbound connections. Your target container also does not need a host port just for Portwarp; it only needs to share a Docker network with pwrp.

Start and sign in

Start only the Portwarp service first, then approve the browser login:

Terminal

docker compose up -d pwrp
docker compose exec pwrp pwrp login
docker compose exec pwrp pwrp status

Open the displayed URL, enter the code, and approve the device.

Map a tunnel to a service

Map each tunnel to a Compose service name:

Terminal

docker compose exec pwrp pwrp tunnels
docker compose exec pwrp pwrp target set "Website" web
docker compose exec pwrp pwrp target list

The target sets the hostname only. The local port still comes from that tunnel's configuration in the Portwarp dashboard.

Connect and save

Terminal

docker compose up -d
docker compose exec pwrp pwrp connect --all --save --detach
docker compose exec pwrp pwrp ps --once

--save reconnects this selection when the container starts again.

Multiple target services

Attach pwrp to every target network. Each tunnel may use a different service or alias:

Terminal

docker compose exec pwrp pwrp target set "Website" web
docker compose exec pwrp pwrp target set "Minecraft" minecraft
docker compose exec pwrp pwrp target set "Database" database
docker compose exec pwrp pwrp connect --all --save --detach

Service names, network aliases, and private IPv4 or IPv6 addresses are supported.

Change or remove a target

Reconnect the affected tunnel after changing its target so the running session uses the new destination:

Terminal

docker compose exec pwrp pwrp target set "Website" new-web
docker compose exec pwrp pwrp connect "Website" --detach

docker compose exec pwrp pwrp target unset "Website"

Logs and health

Terminal

docker compose logs -f pwrp
docker compose exec pwrp pwrp daemon health
docker compose exec pwrp pwrp doctor
docker compose exec pwrp pwrp ps --once

Compose reports the container as healthy when the daemon responds.

Update the image

The CLI does not replace itself inside a container. Pull and recreate it instead:

Terminal

docker compose pull pwrp
docker compose up -d pwrp

The named volume is preserved. Pin a version such as ghcr.io/portwarp/cli:0.3.5 for controlled upgrades.

Networking safety

Targets must resolve to local or private addresses. Public, link-local, multicast, and metadata addresses are rejected.