Concepts

PodWarden manages your servers and the applications running on them. This page explains every concept you'll encounter in the dashboard and documentation.

You don't need to know Kubernetes, Docker internals, or container orchestration to use PodWarden. But you do need a shared vocabulary, so here it is.

---

Servers and Hosts

A host is any server — physical machine, virtual machine, or cloud instance — that you want PodWarden to manage. It could be a rack server in your office, a GPU workstation under someone's desk, a VPS from Hetzner, or a Raspberry Pi in a closet.

PodWarden tracks each host with:

• Hostname and IP address — How to reach it
• Hardware specs — CPU cores, RAM, disk space, GPU model and VRAM (detected automatically)
• Status — Discovered, provisioned, or in a cluster
• Network types — How the server is reachable (see Networks below)

How hosts get into PodWarden

• Automatic discovery — If your servers are on a Tailscale network, PodWarden finds them automatically
• Manual addition — Add any server by IP address or hostname

Provisioning

Provisioning means preparing a server to run applications. When you click "Provision" on a host, PodWarden connects via SSH and installs everything needed: the container runtime, the cluster agent, and GPU drivers if the server has a graphics card.

After provisioning, the server is ready to receive workloads.

---

Clusters

A cluster is a group of servers that work together as a single unit. Instead of manually deciding "this app goes on server A, that app goes on server B," you deploy to the cluster and it handles placement automatically.

Think of it like a pool of resources. A cluster with three servers — one with 32 GB RAM and two with 16 GB each — gives you a combined pool of 64 GB RAM. When you deploy an application that needs 8 GB, the cluster finds a server with enough room and runs it there.

Why clusters?

• Automatic placement — You don't pick individual servers for each app. The cluster schedules work based on available resources.
• GPU matching — If your app needs a GPU, the cluster places it on a server that has one with enough VRAM.
• Resilience — If a server goes down, the cluster can restart workloads on remaining servers.

How clusters are created

• Provision a control plane — Select a host and click "Provision as Control Plane." PodWarden installs the cluster software and creates a new cluster with that server as the first node.
• Register existing — If you already have a Kubernetes/K3s cluster, provide its connection credentials (kubeconfig) and PodWarden registers it.
• Add nodes — Provision additional hosts to join an existing cluster.

Nodes

A node is a server that belongs to a cluster. "Host" and "node" refer to the same physical machine — "host" when talking about the server itself, "node" when talking about its role in a cluster.

---

Apps and Stacks

An app is a catalog grouping — it represents a single application (e.g., "Redmine") that may have multiple deployment variants. A stack is one specific variant — a deployable blueprint that describes everything needed to run the application.

For example, the "Redmine" app might contain these stacks:

• Redmine (standalone)
• Redmine + MySQL
• Redmine + PostgreSQL

You define a stack once, then deploy it to any cluster. Stacks that don't belong to an app appear as standalone stacks.

What's in a stack?

For a detailed explanation of what resource values like 500m CPU and 4Gi RAM actually mean, see Understanding Resource Requirements.

Images

An image is a packaged application — all the code, dependencies, and configuration bundled into a single artifact. Images are stored in registries (like Docker Hub) and pulled to servers when deployed.

You don't build images in PodWarden. You specify which image to use (e.g. postgres:16, ollama/ollama:latest), and PodWarden tells the cluster to pull and run it.

Kinds

Every stack has a kind that determines how it runs:

Most workloads are deployments.

Static vs. configurable environment variables

Stacks have two types of environment variables:

• Static (env) — Fixed values baked into the template. Same for every deployment. Example: OLLAMA_HOST=0.0.0.0
• Configurable (env_schema) — Variables with a name, description, default value, and a required/optional flag. These document what the operator can tune. Example: OLLAMA_MODELS (default: /models, description: "Path where models are stored")

Static vars are set-and-forget. Configurable vars help operators understand what can be changed without reading the app's documentation.

Auto-generated secrets

Configurable variables can include a generate hint that tells the installer how to create a random value automatically. For example, a database password might have generate: "password" and a Rails secret key might have generate: "hex64". When you install a template using the Hub's one-click installer, these values are generated automatically using openssl rand. See Stack Templates for the full list of strategies.

Security context and health probes

Some workloads need special permissions to function. A VPN tunnel needs NET_ADMIN capability to create network interfaces. A network scanner might need privileged mode. PodWarden's security context fields let you declare these requirements in the template.

Health probes tell Kubernetes how to check if your container is working properly. If a liveness probe fails, Kubernetes restarts the container. If a readiness probe fails, traffic stops being sent to it. This prevents stuck containers from silently failing.

Stack types

Every stack is one of two types:

• Single Service — One container, one Kubernetes Deployment. This is the default for most stacks.
• Compose Stack — A multi-service template imported from a docker-compose.yml file. PodWarden handles the translation to Kubernetes resources.

Both PodWarden and PodWarden Hub use the same Apps & Stacks model. When browsing the Hub catalog, you see Applications. When installing or importing, you select which Stack to use. Imported stacks are automatically grouped under their parent app.

Compose stacks

A Compose Stack deploys all services together as a unit. When you deploy a compose stack, PodWarden creates a parent deployment plus child deployments — one for each service. The parent tracks overall status while each child has its own deployment status, logs, and Kubernetes resources.

---

Config Files

Many applications need configuration files at specific paths inside the container — prometheus.yml, mosquitto.conf, nginx.conf, and so on. Config Slots let you define these files as part of a stack and edit their contents per deployment.

How config files work

Config files have two parts:

• Config Schema (on the stack) — Declares which config files the workload accepts: file name, mount path, file type, and optional default content.
• Config Values (on the deployment) — Stores the actual file content per deployment, so operators can customize each config file independently.

When you deploy, PodWarden creates a Kubernetes ConfigMap for each file and mounts it into the container at the declared path. On undeploy, the ConfigMaps are cleaned up automatically.

When to use config files

Use config slots when you want operators to edit configuration file contents directly in the PodWarden UI. This is common for monitoring tools (Prometheus, Grafana), MQTT brokers (Mosquitto), web servers (nginx), and any app that reads a config file on startup.

See Config Files for the full guide.

---

Deployments

A deployment connects a stack (the "what") with a cluster (the "where"). It's the act of saying "run this application on that cluster."

Workflow

1. Create a deployment — pick a stack and a cluster
2. Deploy — PodWarden generates the configuration, sends it to the cluster, and the cluster starts the application
3. Monitor — View status, check logs, see resource usage
4. Undeploy — Stop the application and clean up

You can create multiple deployments for the same stack — deploying the same application to different clusters (staging, production) or the same cluster with different configurations.

---

Storage and Volumes

Applications that need to persist data — databases, file stores, ML models — use volumes. A volume is a folder that survives application restarts.

Volume types

Storage connections

A storage connection is a named, global reference to a shared storage backend — an NFS server or an S3 bucket. Register it once, then reference it from any stack by name.

PodWarden can test storage connections: check NFS reachability, verify S3 authentication, and measure read/write speed.

---

Backups

PodWarden includes a built-in backup system for workload data. Backups use Restic — an incremental, deduplicated, encrypted backup engine — and run as Kubernetes Jobs inside your cluster.

What gets backed up

Persistent volume contents (PVC data). The backup engine mounts the same volumes as your workload and streams them to a storage connection you control — any registered NFS or S3-compatible backend.

Backup policies

A backup policy defines the schedule and settings for a workload's backups. Each policy specifies the workload to back up, the storage target, the schedule (cron expression), and retention rules.

Backup modes

Hot mode supports pre-backup hooks — a command that runs inside the running container before the backup starts. This is how you get consistent database backups: run mysqldump or pg_dumpall first, then back up the resulting file.

Snapshots and retention

Each backup run creates a snapshot. Restic's deduplication means only changed data is stored after the first backup. Retention rules control how many snapshots to keep (by count, daily, weekly).

Restore

Restoring from a snapshot is one click: PodWarden stops the workload, restores the files from the selected snapshot, and restarts it. Any data written after the snapshot was taken is overwritten.

See Backups for the full guide.

---

Ingress and Gateway Nodes

Most self-hosted setups sit behind NAT or a firewall — workloads run on internal servers that aren't directly reachable from the internet. Ingress is how you expose a workload to the outside world.

Gateway nodes

A gateway node is a host in your fleet that has a public IP (or is port-forwarded from your router). It serves as the entry point for incoming internet traffic. You designate any host as a gateway in the PodWarden UI.

Ingress rules

An ingress rule maps a domain (and optional URL path) to a workload or manual backend. When someone visits app.example.com, the ingress rule tells the gateway to forward that traffic to the right application.

Ingress rules support two backend types:

• Managed — Routes to a workload deployed in your cluster.
• Manual — Routes to any reachable IP address or hostname (VMs, NAS web interfaces, other services on your network).

TLS and HTTPS

PodWarden uses Let's Encrypt to automatically obtain and renew TLS certificates. HTTPS is enabled by default on ingress rules — no manual certificate management needed.

Health checks

PodWarden provides three types of health checks for ingress rules: DNS resolution (does the domain point to your gateway?), HTTP (is the site responding?), and TLS (is the certificate valid and not expiring?).

See Ingress, Gateway Nodes & DDNS for the full guide.

---

Dynamic DNS (DDNS)

If your public IP address changes (common with home internet connections), your DNS records need to be updated. DDNS handles this automatically.

PodWarden checks your public IP every 5 minutes and updates DNS records through any of these providers:

Hub DDNS subdomains

The easiest way to get a public URL: connect to PodWarden Hub, allocate a subdomain (e.g. myapp.vxloc.com), and PodWarden keeps the DNS updated automatically. No DNS provider setup or API tokens needed.

See Ingress, Gateway Nodes & DDNS for the full guide.

---

Networks

Not all servers can reach each other. A GPU workstation in your office can't be reached from the public internet, and a cloud VM might not have access to your local NAS.

PodWarden tracks this with network types — simple tags that describe how a server, storage connection, or workload is reachable:

A server can have multiple types. A machine with both a public IP and a Tailscale connection is tagged public + mesh.

Why this matters

Before deploying, PodWarden checks:

• Does the cluster support the network types the workload needs?
• Can the cluster reach the storage the workload depends on?

If there's a mismatch — say you're deploying a workload that needs public access to a cluster that only has mesh — PodWarden warns you before you deploy. It won't block you, but it tells you something might not work.

---

Secrets

Secrets are sensitive values — passwords, API keys, SSH keys, database credentials — stored encrypted in PodWarden. You create them once and reference them from stacks.

Secrets never leave your PodWarden instance. They are not sent to PodWarden Hub.

PodWarden also generates SSH key pairs for host provisioning. These are stored as secrets and used when connecting to servers via SSH.

---

Authentication and Roles

Who can use PodWarden

PodWarden supports three ways to sign in:

• OIDC — Connect to any identity provider (Google, GitHub, Keycloak). Recommended for teams.
• Local users — Email and password accounts created in PodWarden. Good for small teams or offline setups.
• Temporary admin — A username/password set via environment variables for initial setup only.

Roles

Every user has a role that determines what they can do:

MCP tokens

An MCP token is an API key for automation. Instead of a human signing in, a script or CI pipeline uses a token to authenticate. Each token has a role (admin, operator, viewer) that limits what it can do.

MCP tokens start with pwm_ and are shown only once when created. Every API call made with a token is logged (method, path, response status) for audit purposes.

---

PodWarden Hub

PodWarden Hub is an optional cloud service at www.podwarden.com. It provides:

Catalog

A collection of pre-configured stacks organized by category (AI & Machine Learning, Databases, Monitoring, etc.). Each template is a ready-to-deploy stack with tested resource configurations, environment variable schemas, and documentation.

You can browse the catalog on the Hub website or from inside your PodWarden instance.

One-Click Installer

Every template in the catalog can be installed directly to any server with Docker using a one-line command. The installer downloads a bundle (docker-compose.yml + .env + config files), auto-generates secrets, and starts the application. No PodWarden instance required — just Docker. See Stack Templates for details.

Templates (public and private)

• Public templates — Visible to everyone. Community-curated workloads.
• Private templates — Belong to private categories that are only visible to specific organizations. Used for vendor-specific or internal workload distribution.

Categories

Templates are grouped into categories — "AI & Machine Learning", "Databases", "Monitoring", "Development Tools", etc. Categories can be public (everyone sees them) or private (only authorized organizations see them).

Organizations

Every Hub account belongs to an organization. Your subscription, API keys, and private template access are all scoped to your organization.

API keys

A Hub API key (starts with pwc_) authenticates your PodWarden instance against the Hub catalog. Your instance uses the key to browse and import templates. What templates your key can see depends on your organization's access grants.

Import and updates

Importing a template copies it from Hub into your PodWarden instance as a local stack. After import, the definition is yours — change anything you want. PodWarden tracks the Hub origin so you can check for newer versions later.

---

How It All Fits Together

Here's the typical flow:

1. Add servers — Discover via Tailscale or add manually
2. Create a cluster — Provision a server as control plane, add more servers as nodes
3. Create stacks — Build stacks (or import from Hub) describing what to run
4. Deploy — Pick a stack and a cluster, click Deploy
5. Expose to the internet — Set up a gateway node, create ingress rules, configure DDNS
6. Back up your data — Create backup policies for critical workloads
7. Monitor — Check status, view logs, verify health checks
8. Scale — Add more servers to clusters, deploy more workloads, connect to more storage

PodWarden handles the complexity behind the scenes. You work with servers, stacks, and deployments — not Kubernetes manifests, pod specs, or YAML files.