Skip to content

Getting Started ​

This guide gets Podux running with Docker Compose in a few minutes, then adds your first server and proxy. For other install methods, see Docker Installation and Binary Installation.

Prerequisites ​

  • Docker with Docker Compose v2
  • A server running frps (or a third-party frp service); see Compatibility for supported versions

Step 1: Start Podux ​

Create a directory and put a docker-compose.yml in it:

yaml
services:
  podux:
    image: ghcr.io/derrors/podux:latest
    container_name: podux
    restart: unless-stopped
    # Host network: 127.0.0.1 in a proxy points at the host itself
    network_mode: host
    volumes:
      - ./data:/app/pb_data
    environment:
      - TZ=Asia/Shanghai

The container runs as UID 1000, so create the data directory and hand it over first, then start:

bash
mkdir -p data && sudo chown 1000:1000 data
docker compose up -d

Why the host network

With the default bridge network (ports: ["8090:8090"]), 127.0.0.1 in a proxy's local address points at the container itself, not the host. To forward services on the host, use network_mode: host, or enter the host's LAN IP in the proxy.

Step 2: Create the Admin Account ​

Open http://<host>:8090 in a browser. On first visit you are guided to create an admin account with an email and password; use it to sign in afterwards.

Security

If Podux is reachable from the internet, use a strong password and restrict access to port 8090 with a firewall or reverse proxy where possible.

Step 3: Add a Server ​

  1. Click Servers in the sidebar, then Add Server

  2. Fill in the frps connection details:

    FieldDescriptionExample
    NameDisplay nameMy Server
    Server addressIP or domain of the frps hostyour-server.com
    Server portfrps bindPort, default 70007000
    AuthenticationMust match frps; usually a token (frps auth.token)your-token
  3. Save, then start it from the server list. Servers with Auto connect enabled come online every time Podux starts.

Once connected, the server shows as running and starts displaying latency and location.

Step 4: Add a Proxy ​

  1. Click Proxies, then Add Proxy

  2. Choose a proxy type and fill in the settings. For example, to expose local SSH (port 22):

    FieldValue
    Namemy-ssh
    TypeTCP
    ServerThe server added in the previous step
    Local IP127.0.0.1
    Local port22
    Remote port6022
  3. After saving, Podux hot-reloads the frpc configuration automatically; no restart needed.

You can now reach the machine with ssh -p 6022 user@your-server.com.

Already have an frpc config?

Upload your existing frpc.toml on the Import page to preview and import its server, proxies and visitors in one go. Server auth settings, including OIDC, are imported too; unknown proxy types are skipped with a warning.

Overwriting configuration and active connections

An overwrite import replaces the selected records' frpc configuration, clearing omitted options such as plugins and visitor fallback settings rather than merging only non-empty fields. It does not directly reset Podux notes, auto-connect preferences or actual runtime status.

Editing or importing changes to a running server's shared address, authentication or transport configuration automatically restarts that server's frpc and briefly interrupts its tunnels. Proxy-only and visitor-only changes still use hot reload.

PocketBase Admin UI (Optional) ​

Podux includes the PocketBase admin UI (/_/) for inspecting the underlying data; everyday use does not need it. It uses a separate superuser account, which you can create either way:

  • On first start, PocketBase prints a link for creating the first superuser in the startup log (docker compose logs podux)

  • Or create it with a command:

    bash
    docker compose exec podux /app/podux superuser upsert admin@example.com <password>

Next Steps ​

Released under the Apache 2.0 License.