PSW on PSW Documentation

AI Planner: Bring Your Own AI, Pay Nothing to PSW

Mon, 01 Jan 0001 00:00:00 +0000

AI Planner: Bring Your Own AI, Pay Nothing to PSW#

What it is#

The AI planner is what decides how your apps map onto your hardware:

how many LXC targets to create,
which apps go on which target,
how many cores, how much RAM, and how big a rootdisk each target gets,
which target gets GPU passthrough,
which target gets which USB dongle,
where bulk data lives (local ZFS vs NFS from a storage node),
what the storage layout looks like on each Proxmox node.

PSW does not call any AI itself. The planner is a two-step copy/paste protocol:

App Metadata

Mon, 01 Jan 0001 00:00:00 +0000

App Metadata#

What Is It?#

App metadata is the identity card of every app in PSW. It describes everything PSW needs to know about an app: what container image (a packaged snapshot of the app, run by Podman ) to use, which port it listens on, what secrets it needs, whether it supports single sign-on, how to back it up, what other apps it connects to, and more.

Think of it like the nutritional label on a food package. You don’t need to open the box to know what’s inside — the label tells you the ingredients, serving size, and allergens. App metadata tells PSW the ingredients (dependencies), serving size (ports and resources), and allergens (hardware requirements) of each app — so it can deploy and integrate it automatically.

Apps

Mon, 01 Jan 0001 00:00:00 +0000

Apps#

What Is an App?#

An app is anything PSW can deploy and manage for you — a media server, a database, a monitoring dashboard, a password manager. Each app has a deployment recipe (templates and metadata ) describing what it needs and how it fits into your self-hosted solution.

PSW comes with a catalog of ready-to-use apps. You pick the ones you want, and PSW handles the rest: creating targets , configuring networking, setting up secrets , wiring apps together .

Backups

Mon, 01 Jan 0001 00:00:00 +0000

Backups#

Looking for the full disaster-recovery story? This doc covers only per-app bundles — Vaultwarden’s vault entries, Forgejo’s repos, Frigate’s camera footage, Home Assistant’s automation history. For the umbrella view that ties bundles together with your git remote (project shape) and your panic backup (encryption keys + credentials), see disaster-recovery.md . Three layers, restored in three different ways, each documented independently. The umbrella doc is the right starting point if you’ve never actually walked through a recovery before.

Bootstrap

Mon, 01 Jan 0001 00:00:00 +0000

Bootstrap#

What Is It?#

Bootstrap is the one-time setup process that brings your self-hosted solution to life. It takes a bare Proxmox node and turns it into a fully functional platform — with a database, reverse proxy, authentication, a git server, and a web dashboard — all in a single command.

Think of it like building the foundation of a house. You do it once, and everything else (your apps ) gets built on top of it.

Conventions

Mon, 01 Jan 0001 00:00:00 +0000

Conventions#

What Is a Convention?#

A convention is a standardized way for apps to plug into shared infrastructure automatically. Instead of manually configuring Traefik routes, SSO clients, or monitoring targets for every app you install, PSW uses conventions to generate all that wiring for you.

When you add Jellyfin , PSW doesn’t just deploy it — it also:

Creates a Traefik route so https://jellyfin.yourdomain.ca works
Registers an SSO client with Authelia (if the app supports it)
Adds a Prometheus scrape target (if the app exposes metrics)
Creates a backup plan for Backrest (if the app has data worth backing up)
Adds a dashboard entry on Homepage

All of this happens because Jellyfin’s metadata declares which conventions it participates in. You don’t configure any of it — PSW handles it.

Convergence

Mon, 01 Jan 0001 00:00:00 +0000

Convergence#

What Is It?#

Convergence is PSW’s automatic deployment engine. It runs on your bootstrap target (the server where core apps live) and continuously makes sure your self-hosted solution matches what’s defined in your user project files.

Think of it like a diligent assistant: every 5 minutes, it checks “did anything change in the project?” and if so, it applies those changes — creating targets, deploying apps, wiring them together, or tearing down things you’ve removed.

Deployment Plan: The Blueprint for What Runs Where

Mon, 01 Jan 0001 00:00:00 +0000

Deployment Plan: The Blueprint for What Runs Where#

What It Is#

Imagine you’re building a house. You tell the architect “I want a garage, a home theater, and a wine cellar,” and they design the foundation that supports what you need — the right thickness under the theater for soundproofing, a reinforced slab for the garage, drainage for the cellar.

The deployment plan works the same way. You tell PSW what apps you want; an AI of your choice designs the LXC targets, the ZFS storage layout, the GPU passthrough, and the NFS wiring that fits those apps onto your hardware. PSW never talks to an LLM itself — it renders a self-contained prompt you paste into whichever AI you already use (ChatGPT, Claude.ai, Gemini, a local LLM, whatever), and it validates the JSON reply against a strict schema before saving anything. See AI Planner for the full protocol.

Disaster Recovery

Mon, 01 Jan 0001 00:00:00 +0000

Disaster Recovery#

What It Is#

Disaster recovery is the answer to one question: “My server burned down — can I bring everything back?”

PSW’s answer is yes, and the way it gets to “yes” is by treating your setup as three independent things, kept in three different places, restored in three different ways. Lose one and the other two can usually carry you. Lose all three and you’re rebuilding from memory.

GitOps

Mon, 01 Jan 0001 00:00:00 +0000

GitOps#

What Is It?#

GitOps is a way of managing your self-hosted solution where a git repository is the single source of truth for everything. Instead of logging into servers and making changes by hand, you describe what you want in text files, commit them, push — and the system automatically makes it happen.

Think of it like writing a shopping list and handing it to someone who goes to the store for you. You don’t walk the aisles yourself — you just write down what you need, and it gets done. In PSW, the “shopping list” is your user project , and the “someone” is the convergence engine.

Hardware

Mon, 01 Jan 0001 00:00:00 +0000

Hardware#

What Is It?#

nodes/<name>/hardware.yml is a complete, machine-readable inventory of one of your servers. It says what CPU is in there, how much RAM, what disks are attached, which NICs (network interface controllers — the chips that connect a computer to the network) are wired up, and which GPUs and USB dongles are plugged in.

PSW writes one of these files per Proxmox node . Once it exists, every downstream tool — the AI planner , the Proxmox installer , the OPNsense installer, the dashboard, the wizard — reads it as the source of truth for what that server actually is.

High Availability

Mon, 01 Jan 0001 00:00:00 +0000

High Availability#

Status: roadmap. PSW can form Proxmox clusters today (psw node cluster), but the pieces below — ha: true on targets, shared_storage: in network.yml, psw maintenance start/end, automatic failover wiring — are not yet implemented. This page captures the intended design so contributors and early users have one north star to build toward.

What Is It?#

High availability (often shortened to HA) means your apps keep running even when a server fails or needs to go offline for maintenance. If one of your Proxmox nodes goes down — whether from a dead power supply, a crashed disk, or because you’re installing updates — your targets automatically restart on another node. Your family keeps streaming, your passwords stay accessible, your smart home keeps working.

Idempotency

Mon, 01 Jan 0001 00:00:00 +0000

Idempotency#

What Is It?#

Idempotency means that running the same operation twice produces the same result as running it once. Nothing breaks, nothing duplicates, nothing changes the second time — because the system checks what already exists before acting.

Think of it like flipping a light switch to “on.” If the light is already on, flipping the switch again doesn’t turn on a second light or cause an error — it just stays on. Every operation in PSW works the same way: if the desired state already exists, it does nothing.

Infrastructure: Nodes, Targets, and Management Hosts

Mon, 01 Jan 0001 00:00:00 +0000

Infrastructure: Nodes, Targets, and Management Hosts#

The Big Picture#

Your self-hosted solution ’s infrastructure has three layers, from bottom to top:

┌───────────────────────────────────────────────────┐
│ Apps (Jellyfin, Sonarr, Grafana, ...) │ ← What you care about
├───────────────────────────────────────────────────┤
│ Targets │ ← Where apps run
├───────────────────────────────────────────────────┤
│ Nodes & Management Hosts (Proxmox, OPNsense) │ ← The physical foundation
└───────────────────────────────────────────────────┘

Let’s go through each layer.

Management Hosts#

A management host is a machine that exists on your network before PSW does anything. These are the physical infrastructure that make everything else possible.

Local AI

Mon, 01 Jan 0001 00:00:00 +0000

Local AI#

What Is It?#

Local AI means you run a chatbot — and eventually voice, image generation, photo search, and document tagging — on your own hardware, with the data staying inside your house. No subscriptions. No cloud. The kid asks the speaker to turn off the kitchen light, the family chats about dinner with a private assistant, the photo app finds “beach 2018” — and none of it ever leaves the box.

Monitoring

Mon, 01 Jan 0001 00:00:00 +0000

Monitoring#

What Is It?#

Monitoring is how PSW answers the question “is everything still working?” without you having to SSH around and poke at services. It collects two kinds of signals from every target and every app :

Metrics — numbers over time: CPU, memory, disk, response times, queue lengths, request counts
Logs — the text each service writes as it runs: errors, warnings, requests served, things that crashed

Those signals get shipped to a central place, displayed on dashboards, and — when something goes wrong — turned into a phone notification so you actually find out about it.

Networking

Mon, 01 Jan 0001 00:00:00 +0000

Networking#

What Is It?#

Networking is everything that lets the parts of your self-hosted solution find and talk to each other — your Proxmox servers, the LXC containers running your apps, your phone browsing the dashboard, and the wider internet reaching an exposed app . None of that works without a router sitting in the middle handing out IP addresses, resolving domain names, and shuttling packets.

PSW supports two router scenarios, picked once at wizard time:

Operations Mode

Mon, 01 Jan 0001 00:00:00 +0000

Operations Mode#

What Is It?#

Everything up to and including the Setup Wizard is a one-time experience — you run it once, bare metal to live platform, and never again. Operations mode is what comes after: the dashboard you open every day to see what’s running, add new apps , watch convergence runs, and check whether anything is on fire.

The wizard was the installer. Operations mode is the control panel.

Where Do You Find It?#

Two doors to the same room:

Philosophy

Mon, 01 Jan 0001 00:00:00 +0000

Philosophy#

Self-Hosted Solution, Not Homelab#

This is the most important thing to understand about PSW.

The word “homelab” implies a laboratory — a place to experiment, break things, learn, and tinker. That’s a valid hobby, but it’s not what PSW is for.

PSW builds a self-hosted solution: production-quality infrastructure that you depend on. The same apps your family uses to watch movies, the same password manager that stores your banking credentials, the same smart home system that controls your locks. These services must be solid, reliable, and self-healing — not experiments.

Project Graph & Validation

Mon, 01 Jan 0001 00:00:00 +0000

Project Graph & Validation#

What Is the Project Graph?#

The project graph is a single, immutable snapshot of your entire user project — every app , target , secret , provider , and the relationships between them — loaded once and used everywhere.

Think of it like a photograph of your self-hosted solution’s configuration at a point in time. PSW takes this snapshot, validates it for problems, and then hands it to the systems that need it: the convention engine, the deployment pipeline, DNS reconciliation, and more.

Project Launcher

Mon, 01 Jan 0001 00:00:00 +0000

Project Launcher#

The project launcher is the first screen you see when you run psw wizard with no arguments. It’s where you decide which user project to work with – either by creating a new one or opening one you’ve worked on before. (The launcher belongs to the installer UI; once a project is bootstrapped you switch to psw dashboard, which opens an existing project directly and has no launcher screen of its own.)

Providers

Mon, 01 Jan 0001 00:00:00 +0000

Providers#

What Is a Provider?#

A provider is a backend service that handles a piece of foundational infrastructure your self-hosted solution needs to function. Think of providers as the plumbing behind the scenes — they manage DNS resolution, IP address assignment, and SSL certificates so your apps are reachable by name with secure HTTPS connections. The three networking providers (local DNS, WAN DNS, DHCP) are the core of how networking works in PSW.

PSW Documentation Site

Mon, 01 Jan 0001 00:00:00 +0000

PSW Documentation Site#

What Is It?#

PSW Documentation is the same set of concept docs you’re reading right now — every file under docs/concepts/ plus the project README — rendered as a real, searchable, browsable website and shipped with your self-hosted solution. It lives at https://docs.<your-domain>/ (e.g. https://docs.casaeureka.ca/) and is served by your own server, alongside Jellyfin , Grafana , and everything else.

So the next time you wonder “wait, what does idempotency mean again?” or “how do I expose an app remotely?”, you don’t need to fish for a GitHub tab — open docs.<your-domain>/ and search.

Remote Access

Mon, 01 Jan 0001 00:00:00 +0000

Remote Access#

What Is It?#

Remote access lets you reach your apps from anywhere on the internet — not just from your local network. When you expose an app, it becomes accessible at its public subdomain (e.g., https://jellyfin.yourdomain.ca) from your phone, a coffee shop, or anywhere else.

Remote access sits on top of your normal networking — it doesn’t replace the router or DNS, it just adds an internet-side entry point for apps you explicitly expose.

Reset and Removal

Mon, 01 Jan 0001 00:00:00 +0000

Reset and Removal#

What Is It?#

Reset is PSW’s answer to “I want to undo something.” That covers a range: uninstalling a single app, wiping a whole test project clean, rebuilding a broken VPS, or nuking everything so you can start over. PSW gives you one command per size, each with its own safety rails.

Think of the scale like this:

Size of undo	Command	What dies
One app, clean uninstall	`psw app remove <name>`	That app’s containers, data, database, convention files
One target no longer needed	`psw target delete <name>`	The entry in `network.yml` (actual LXC survives until a full reset)
The whole bootstrap & retry	`psw deploy bootstrap --clean`	Just the bootstrap progress file, so bootstrap starts fresh
The whole setup, rebuild from scratch	`psw deploy reset --confirm`	Every managed LXC, every ZFS dataset, every PSW-managed DNS + DHCP record, every generated project file
The remote VPS, rebuilt in place	`psw remote rotate-vps`	The VPS’s OS reinstalled; certs preserved

All of these are declarative-first — you don’t destroy anything directly. You change a file (or run a command that changes a file), commit, and convergence or an explicit deploy step does the actual teardown in a safe, predictable order.

Secrets

Mon, 01 Jan 0001 00:00:00 +0000

Secrets#

What Are Secrets?#

Secrets are the passwords, API keys, tokens, and credentials your apps need to function. Things like database passwords, SSO signing keys, and provider API tokens.

PSW encrypts all secrets using SOPS (Secrets OPerationS) with age encryption, so they’re safe to store in your git repository. You never have to worry about accidentally leaking a password in a commit — everything in secrets/ is encrypted before it touches git.

Single Sign-On

Mon, 01 Jan 0001 00:00:00 +0000

Single Sign-On#

What Is It?#

Single Sign-On (SSO) means you log in once, and every app on your setup recognises you. No per-app account, no twenty-passwords-for-twenty-apps. You visit Jellyfin without being logged in, you’re redirected to a login page, you enter your password, you’re back on Jellyfin — and now Grafana , Forgejo , the operations dashboard , and everything else just let you in too.

Think of it like the wristband at a multi-venue festival. You queue once at the gate, they check your ID, and from then on every stage just scans the band.

Split-Horizon DNS

Mon, 01 Jan 0001 00:00:00 +0000

Split-Horizon DNS#

What Is It?#

Split-horizon DNS means the same domain name points to different addresses depending on where you are. When you type jellyfin.yourdomain.ca into your browser:

At home → it resolves to your Traefik server’s internal IP (e.g., 10.10.0.100) — traffic stays on your local network
On the internet → it resolves to your public VPS IP (e.g., 203.0.113.50) — traffic goes through a tunnel

Think of it like a restaurant with two entrances: one for locals (the back door, fast and direct) and one for visitors (the front door, through the lobby). Both entrances lead to the same restaurant, but the path is different depending on who you are.

Stacks

Mon, 01 Jan 0001 00:00:00 +0000

Stacks#

What Is It?#

A stack is a pre-built bundle of apps that work well together. Instead of adding apps one by one, you can install an entire group with a single command.

Think of it like a meal kit: instead of buying each ingredient separately, you get a box with everything you need for a complete recipe. A stack gives you a curated set of apps that form a complete solution — media streaming, home automation, monitoring, and so on.

Storage

Mon, 01 Jan 0001 00:00:00 +0000

Storage#

What Is It?#

“Storage” in PSW means the disks and filesystems your apps store their data on. It’s split across three places:

ZFS pools — the big shared disks living directly on your Proxmox node , carved into datasets (like labeled drawers)
Container root disks — a per-target small filesystem where the operating system and local-only app data live
Podman-managed volumes — for app data that should stay local to one container, not shared

An AI planner sits at the front of all this: you tell it what apps you want and it designs the whole layout — pool configuration, datasets with the right tuning, rootdisk sizes per target — based on your actual hardware and the apps you picked. PSW renders the prompt; you paste it into whatever AI you already use (Claude.ai , ChatGPT, Gemini, a local LLM, etc.); you paste the reply back into PSW. PSW validates it and writes nodes/<name>/storage.yml. No API keys collected anywhere in PSW.

The Execution Plan

Mon, 01 Jan 0001 00:00:00 +0000

The Execution Plan#

What Is It?#

When convergence decides it’s time to deploy your apps , it doesn’t just march through a fixed list of steps. Instead, it builds an execution plan — a map of every piece of work that needs to happen, along with which pieces depend on which others. Then a runner walks that map, doing as much work in parallel as the dependencies allow.

Think of it like cooking a multi-course dinner for twelve people. You could cook one dish at a time from start to finish — start the pasta sauce, finish the pasta sauce, then start the salad, then the roast, then dessert. You’d eat at midnight. What you actually do is look at the whole menu, notice that the roast takes two hours but the salad takes five minutes, and start the roast first. While it’s in the oven, you chop the salad, simmer the sauce, and prep dessert. Some things still have hard orderings (“don’t plate the pasta before the sauce is done”), but everything else overlaps.

The Setup Wizard

Mon, 01 Jan 0001 00:00:00 +0000

The Setup Wizard#

What Is It?#

The Setup Wizard is the guided, browser-based experience that walks you from bare hardware in a box to a running, production-grade self-hosted solution . It’s the front door to PSW — the one thing you open the first time.

You don’t memorize commands, edit YAML by hand, or SSH into anything. You open a web page, answer questions, click buttons, and by the end you have a full platform: a Proxmox hypervisor, the seven core apps , HTTPS with valid certificates, Single Sign-On , and automatic convergence — all driven from your laptop.

User Project

Mon, 01 Jan 0001 00:00:00 +0000

User Project#

What Is It?#

A User Project is a folder on your computer that describes your entire self-hosted solution . Think of it as the blueprint for your entire infrastructure — it tells PSW which apps you want, where they should run, how your network is configured, and what secrets (passwords, API keys) are needed.

It’s also a git repository (a version-controlled folder where every change is recorded as a snapshot you can inspect or undo), meaning every change you make is tracked. You can go back in time, see what changed, and even push your project to a remote server (like Forgejo ) to trigger automatic deployments .

Wiring

Mon, 01 Jan 0001 00:00:00 +0000

Wiring#

What Is It?#

Wiring is how PSW automatically connects apps to each other. When you install Sonarr and Prowlarr , they need to know about each other — Sonarr needs Prowlarr’s address and API key to search for content. Wiring takes care of that for you, automatically, without you touching a single settings page.

Think of it like an electrician connecting outlets in your house. You decide where the appliances go (which apps on which targets ) — the electrician wires them together so they can talk to each other.

Wizard Prefill

Mon, 01 Jan 0001 00:00:00 +0000

Wizard Prefill#

What Is It?#

Wizard prefill is a way to hand psw wizard a JSON file that already contains everything the first wizard page would ask you — your domain, your SSH key path, your OPNsense and Cloudflare credentials, and optionally your SMTP relay settings — so PSW can skip that page entirely and drop you straight on the next step (Hardware).

You run it like this:

psw wizard --project ~/homelab1 --prefill ~/.config/psw/homelab1.json

PSW reads the file, runs the exact same setup pipeline the first page’s “Initialize Project” button would run, and then opens the wizard in your browser already one step ahead.