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 Tailscale account for automatic host discovery (not needed if all hosts are on the same LAN)

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 (host networking for Tailscale/SSH access)
  • 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. JWT secret is auto-generated.
4. No auth — development only, not recommended.

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. Set Up Tailscale (Optional)

If your servers are on a Tailscale network:

1. Go to Settings → Tailscale
2. Enter your Tailscale API Key and Tailnet name
3. Optionally set a Discovery Tag to filter hosts (e.g. infra to only discover hosts tagged tag:infra)
4. Click Save

PodWarden automatically discovers all Tailscale hosts in your network. Hosts appear on the Hosts page.

Tailscale is not required for LAN-only setups. If all your hosts are on the same local network, you can skip Tailscale and add hosts manually by IP or hostname.

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

With Tailscale: Hosts are discovered automatically. Go to Hosts to see them.

Without Tailscale: Manually add hosts by IP or hostname on the Hosts page. This works well for LAN-only setups where all machines are on the same network.

Manually-added hosts can be edited (click the pencil icon next to the address) or deleted from the host detail page. Tailscale-discovered hosts are managed by Tailscale and cannot be edited or deleted.

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 & DDNS — Expose services to the internet
• PodWarden Hub — Catalog, subscriptions, and templates
• MCP Integration — AI agent access via Model Context Protocol