---
name: "homelab_design"
description: "Design a home server lab from scratch or upgrade an existing one: hardware picks, network segmentation, services stack, backups, budget, and a phased build plan. Use when someone wants to plan, price, or grow a homelab."
---

# Homelab Design

## Purpose

Turn vague "I want a homelab" energy into a concrete, buildable plan: what to buy, how to network it, what to run, how to back it up, what it costs, and what gets built in what order. The method is the product: gather constraints, score trade-offs openly, then produce a phased plan instead of a one-shot shopping list.

## Workflow

1. **Discovery.** Ask (or infer from what you already know): budget ceiling, noise tolerance (rack gear is loud), power cost sensitivity, technical comfort level, primary use cases (media, dev, smart home, AI/LLM, storage), ISP situation (CGNAT? bridgeable modem?), and whether they already own hardware.
2. **Size the compute.** Pick one of the three build tiers in `references/build-tiers.md` by matching constraints, not aspirations. RAM is almost always the binding constraint: 16 GB minimum, 32 GB if the stack grows past ~15 containers. One box first; add a second box only when a real limit is hit.
3. **Design the network.** Use `references/vlan-plan-template.md`: start with 4-5 VLANs (trusted, servers, IoT, guest, management), assign subnets once and never renumber, decide router platform (OPNsense, pfSense, or UniFi) and whether the ISP gateway can be bridged. Flat network is acceptable for tier 1; document it as deferred, not skipped.
4. **Choose the stack.** One service per category at first, in this order: DNS/adblock → reverse proxy → password manager → monitoring → everything else. See `references/services-stack.md` for category picks and why. Bind app ports to loopback behind the reverse proxy; segment Docker into edge and backend networks.
5. **Plan backups before buying disks.** Apply 3-2-1 (three copies, two media types, one offsite) with zero manual steps. restic or Kopia, encrypted, to a local target plus an offsite (Backblaze B2, friend's house, or rclone to cloud). RAID is redundancy, not backup; say so explicitly.
6. **Price it.** Run `bin/homelab_tco.py` with the candidate hardware to get 5-year total cost of ownership (purchase + electricity). Present price ranges with the date checked and a note to verify live prices, since mini-PC pricing is volatile.
7. **Output the phased plan.** Follow the Output Contract below. Phases must be shippable: each ends with a working, monitored state, never a half-wired pile.

## Output Contract

A homelab design always contains, in this order:

1. **Constraints summary** — the user's answers from discovery, in 5-8 bullets.
2. **Trade-off analysis** — the real decision points with both sides stated plainly (e.g. mini PC vs used rack server: silence and power vs purchase price and ECC; one box vs two: simplicity vs failure isolation). Pick a side and say why.
3. **Hardware list** — exact model class + specs + price range + where to source (used market vs retail). Mark anything unpriced as "price not verified".
4. **Network plan** — filled VLAN table from the template, router choice, how remote access works (WireGuard/Tailscale, no port-forwarded services to the internet).
5. **Services stack** — category table with the one pick per category and the deploy order.
6. **Backup design** — the three copies, where they live, what runs on schedule, restore test procedure.
7. **Phased build plan** — 3-4 phases; each phase lists what gets bought, built, and verified before moving on.
8. **Budget + TCO** — upfront total and the 5-year TCO output from the calculator.

## Operating Rules

1. Never invent a price, wattage, or spec. Price ranges in the references are dated; if they are stale, verify with a web search or mark them unverified. Say "check live price" rather than guessing.
2. A homelab that grows one working service at a time beats one that arrives fully formed and half-understood. Do not spec all 30 containers in phase 1.
3. Security is designed, not assumed: every plan includes VLAN segmentation (or a documented deferral), the reverse proxy rule (nothing app-facing exposed directly), and the 3-2-1 backup design. No plan ships without all three addressed.
4. No em dashes anywhere in the output. No hype language. Plain, direct sentences.
5. When the user already owns hardware, design around it; do not re-spec a shopping list to justify a fresh build.