Introduction
What is PodWarden and what problems does it solve
PodWarden is a platform for managing servers and the applications running on them. You add your servers, create templates for the applications you want to run, and deploy them — PodWarden handles the rest.
Who is PodWarden for?
PodWarden is built for teams that have servers but don't have (or don't want) dedicated DevOps engineers. You might be:
- A development team running your own staging and production servers
- A small company self-hosting business applications
- A lab or research team running AI/ML workloads on GPU machines
- A homelab enthusiast who's outgrown manual SSH-and-docker-compose workflows
You don't need to know Kubernetes, YAML, or container orchestration. PodWarden abstracts that away. You work with servers, templates, and deployments.
What does PodWarden do?
| Problem | How PodWarden solves it |
|---|---|
| "I have servers but no easy way to deploy apps to them" | Add servers to PodWarden, create stack templates, and deploy with one click |
| "I don't know which server has room for another app" | PodWarden tracks CPU, RAM, and GPU across your fleet and places workloads automatically |
| "My NFS share works from some servers but not others" | Network-aware storage checks warn you before deploying to a server that can't reach the storage |
| "Someone deployed something last week and now it's broken" | Full deployment history with rollback — see exactly what changed and revert instantly |
| "We need to run AI models and I don't know which server has a GPU" | GPU discovery and VRAM-aware placement — PodWarden matches workloads to available GPUs |
| "Setting up new servers takes hours of SSH and manual config" | One-click provisioning installs everything via Ansible — Docker, cluster agent, GPU drivers |
| "I want pre-made app templates, not to write config from scratch" | PodWarden Hub has a catalog of curated templates — import and deploy in minutes |
| "I need to expose my app to the internet with HTTPS" | Gateway nodes, ingress rules, and automatic Let's Encrypt certificates — no manual reverse proxy setup |
| "My home IP keeps changing and breaking DNS" | Built-in DDNS updates Cloudflare, DuckDNS, or Hub-managed subdomains automatically every 5 minutes |
| "I don't have a domain — I just want a public URL" | Allocate a Hub DDNS subdomain (e.g. myapp.vxloc.com) with one click |
| "I need backups but don't want to set up another tool" | Built-in Restic backups with scheduling, retention, hot/cold modes, and one-click restore |
| "Each deployment needs different config files" | Config file slots let operators edit app config (YAML, TOML, INI) per deployment in the UI |
Key Concepts
Before diving in, familiarize yourself with PodWarden's vocabulary: Concepts explains every term — hosts, clusters, templates, deployments, volumes, networks, backups, ingress, and more — in plain language.
Architecture
| Layer | Technology | Purpose |
|---|---|---|
| Frontend | Next.js 15, React 19, Tailwind | Dashboard UI with OIDC auth |
| Backend | FastAPI, asyncpg | REST API with JWT auth |
| Database | PostgreSQL 16 | Fleet data, settings, users |
| Runtime | Docker Compose | Runs on your server with host network access |
PodWarden runs entirely on your infrastructure. All data stays on your servers.
PodWarden Hub
PodWarden Hub is an optional cloud service that extends PodWarden with a centralized workload catalog. Browse templates at www.podwarden.com, connect your PodWarden instance with an API key, and import templates directly. Hub also provides image registry caching, DDNS subdomain allocation, team collaboration, and private template catalogs for organizations.
Hub is a convenience layer, not a requirement. PodWarden works fully offline without it.
Documentation Overview
| Section | Description |
|---|---|
| Concepts | Key terms and ideas — start here if you're new |
| Getting Started | Install PodWarden and run your first deployment |
| Architecture | System components and design decisions |
| User Manual | Page-by-page UI reference with screenshots for every screen |
| Guides | In-depth guides for workloads, storage, networking, ingress, backups, config files, and deployment |
| PodWarden Hub | Cloud catalog, dashboard, admin portal, and subscriptions |
| MCP Integration | AI agent access via Model Context Protocol |
| API Reference | REST API endpoints for PodWarden and PodWarden Hub |
| Hard Questions | Honest answers to tough objections |