Getting Started

Prerequisites

For the PodWarden server:

• Docker and Docker Compose v2 — install Docker
• openssl — for generating secrets (pre-installed on most Linux distros)
• A server with at least 2 CPU cores, 2 GB RAM, and 20 GB disk

For target hosts (machines PodWarden will provision):

• SSH access as root with key-based authentication
• See Prepare Hosts for Provisioning below

Optional:

• A mesh VPN (Tailscale, Nebula, WireGuard, etc.) for connecting hosts across sites. PodWarden treats any mesh interface on a host as a standard network interface — see Networking for the mesh-slot model.

Install

Run the one-liner on your server:

curl -fsSL https://www.podwarden.com/install.sh | bash

The installer is interactive — it checks prerequisites, asks a few questions, generates configuration, pulls Docker images, and starts PodWarden.

What the Installer Asks

What the Installer Creates

Everything goes into /opt/podwarden/ (configurable via INSTALL_DIR):

• .env — All configuration and secrets (permissions 600)
• docker-compose.yml — Production compose file with three services:
  • podwarden-db — PostgreSQL 16
  • podwarden-api — FastAPI backend (uses host networking so it can reach hosts over LAN, mesh VPN, or public IP)
  • podwarden-ui — Next.js frontend

Database passwords, encryption keys, and JWT secrets are auto-generated. You never need to edit the compose file — all settings are controlled through .env.

Authentication

The installer offers four auth methods:

1. Temporary admin (default) — generates a username and password. Good for initial setup. The password is shown once during install — save it.
2. OIDC SSO — connect to Keycloak, Auth0, Okta, or any OIDC provider. Asks for issuer URL, client ID, client secret, and required group.
3. Local users — email and password accounts managed in PodWarden Settings.
4. No auth — development only, not recommended.

A JWT secret (PW_JWT_SECRET) is auto-generated for all auth methods. It is written to .env and used to sign session tokens — do not lose it.

You can change the auth method later by editing /opt/podwarden/.env and restarting.

Verify

Once the installer finishes, open the dashboard:

http://<your-server-ip>:3000

Check the API health endpoint:

curl http://localhost:8000/api/v1/health

Initial Setup

1. Sign In with Temporary Admin

The installer generates a temporary admin username and password (shown once during install). Open the dashboard and sign in with those credentials.

You'll see a banner reminding you that temporary admin is active.

2. Create a Permanent Admin User

1. Go to Settings → Users
2. Click Create User
3. Set a username, email, and password
4. Assign the admin role

3. Disable Temporary Admin

Once your permanent admin user is created, disable the temporary credentials:

cd /opt/podwarden

# Clear the temp admin values
sed -i 's/^PW_TEMP_ADMIN_USER=.*/PW_TEMP_ADMIN_USER=/' .env
sed -i 's/^PW_TEMP_ADMIN_PASSWORD=.*/PW_TEMP_ADMIN_PASSWORD=/' .env

# Recreate the API container to pick up the change
docker compose up -d --force-recreate podwarden-api

Now sign in with your newly created admin account. The temporary admin login is no longer available.

Later, you can add OIDC SSO (Keycloak, Auth0, Okta) — see Configuration for details.

4. Mesh VPN (Optional)

PodWarden has no Tailscale-specific configuration. If your hosts are connected by a mesh VPN (Tailscale, Nebula, WireGuard), PodWarden will discover the mesh interface during the host probe and treat its address as a standard host_interfaces.kind='mesh' row alongside any LAN or public addresses. The mesh interface is then available everywhere LAN/public addresses are — for SSH, K3s control-plane joins, and storage reachability checks.

You don't need to do anything special at install time. Add hosts by their address (mesh, LAN, or public IP) on the Hosts page; the Networking guide explains how PodWarden picks the connection path when a host has multiple interface kinds.

5. Prepare Hosts for Provisioning

Before PodWarden can provision a host (install K3s, Docker, GPU drivers), it needs SSH access as root with key-based authentication.

Create an SSH Key Pair

1. Go to Settings → SSH Keys
2. Click Create Key Pair — PodWarden generates and securely stores an ed25519 key pair
3. Copy the public key shown after creation

Distribute the Public Key

On each target host, add the public key to root's authorized keys:

sudo mkdir -p /root/.ssh
echo "ssh-ed25519 AAAA... podwarden" | sudo tee -a /root/.ssh/authorized_keys
sudo chmod 700 /root/.ssh
sudo chmod 600 /root/.ssh/authorized_keys

Enable Root SSH Access

Many Linux distributions disable root login by default, or hardening scripts may restrict it. Check and fix these common blockers:

1. Allow root login with keys — edit /etc/ssh/sshd_config (or any file in /etc/ssh/sshd_config.d/):

# Change from "no" to "prohibit-password" (allows key auth, blocks password auth)
PermitRootLogin prohibit-password

2. Check AllowUsers — if AllowUsers is set, add root:

# Example: was "AllowUsers ip", change to:
AllowUsers ip root

3. Restart SSH to apply changes:

sudo systemctl restart sshd

4. Check fail2ban — if PodWarden's IP was banned during earlier failed attempts:

# Check if banned
sudo fail2ban-client status sshd

# Unban if needed
sudo fail2ban-client set sshd unbanip <podwarden-server-ip>

5. Check firewall — ensure SSH (port 22) and K3s ports are open:

# SSH access from PodWarden server
sudo ufw allow from <podwarden-server-ip> to any port 22

# K3s ports (required after provisioning)
sudo ufw allow 6443/tcp   # K3s API server
sudo ufw allow 10250/tcp  # Kubelet metrics
sudo ufw allow 8472/udp   # Flannel VXLAN (pod networking)

Open the K3s ports before provisioning. If your host was cloned from another VM, remove any stale firewall rules that don't apply (e.g. old PodWarden UI/API ports).

Verify SSH Access

Test from the PodWarden server:

# From the PodWarden API container
docker exec -it podwarden-api ssh -i /tmp/ssh_key root@<host-ip> hostname

Or use the Probe button on the host's page in the PodWarden UI — a successful probe confirms SSH connectivity.

6. Add Hosts

Add hosts by IP address or hostname on the Hosts page. PodWarden probes the host over SSH to discover its hardware, OS, and all network interfaces (LAN, mesh, public). Each interface is recorded in the host's interface table and is later usable as a connection path for provisioning, ingress, and storage.

Hosts can be edited (click the pencil icon next to the address) or deleted from the host detail page.

7. Create or Register a Cluster

Provision a new cluster: Select a host → Provision as Control Plane → PodWarden installs K3s and creates a cluster.

Register an existing cluster: Go to Clusters → Create → provide a name and kubeconfig.

8. Deploy a Workload

1. Create a Stack (or import one from PodWarden Hub)
2. Create a Deployment linking the definition to a cluster
3. Click Deploy

See Workloads for details.

9. Connect to PodWarden Hub (Optional)

PodWarden Hub provides a curated catalog of pre-configured stacks:

1. Sign up at www.podwarden.com
2. Create an API Key under Dashboard → API Keys
3. In PodWarden, go to Settings → Hub and enter the Hub URL and API key
4. Import templates from Apps & Stacks → Import from Hub

See Connecting to Hub for the full guide.

Updating

cd /opt/podwarden
docker compose pull
docker compose up -d

Migrations run automatically on API startup.

Uninstalling

cd /opt/podwarden
docker compose down -v   # -v removes database volume
cd / && rm -rf /opt/podwarden

What's Next

• Architecture — System design overview
• Configuration — All settings and environment variables
• Networking — Network-aware scheduling
• Ingress, Gateway Nodes & DDNS — Expose services to the internet
• PodWarden Hub — Catalog, subscriptions, and templates
• AI & MCP Integration — AI agent access via Model Context Protocol