How to Set Up a Proxmox Home Server With Claude (The Prompt I Wish I’d Had)

The first thing I built on my Proxmox home server was a media container, and it could not read a single one of my media files. Permission denied, every time. The mount was right. The host permissions were fine. After two hours I did what everybody does eventually, which is chmod 777 the whole directory, and it still did not work.

The service ran as user 999 inside the container. On the host, that user is 100999. Unprivileged containers shift every user ID by 100000, so every permission I had been carefully fixing belonged to somebody who did not exist.

Short version for the skimmers: a Proxmox home server setup goes fine with Claude’s help, but only if you hand it the five facts about your hardware it cannot see. Get those wrong and it will confidently build you something broken. Below you’ll find the hardware requirements for everything you might want to run, the exact prompt to paste, and the eight mistakes that cost me the most time.

Claude and I circled that permissions problem for an hour, because I never mentioned the container was unprivileged and it never thought to ask. That is the shape of nearly every problem in this post. Not the model being wrong. The model filling in a sensible default for something about my machine it cannot see, and me not knowing which facts were worth saying out loud.

Why Proxmox instead of just installing Docker

I went back and forth on this for weeks before committing, so here is the honest version.

Proxmox is a Debian box with a good web interface for running virtual machines and containers. That’s it. What you get for the small amount of overhead is the ability to snapshot a service before you break it, roll it back in nine seconds when you do break it, and keep your download client in a box that physically cannot see your documents.

If you are running two services and you already know Docker, Docker on a plain Ubuntu box is less work. I’m not going to pretend otherwise. Proxmox starts paying for itself around the fourth service, or the first time you want Windows and Linux on the same hardware without having to pick a favorite.

One thing I wish somebody had said to me on day one: most of what you run on Proxmox will be LXC containers rather than full virtual machines, and containers are so much cheaper it changes what you can afford to run. A container running a file server idles at maybe 80MB of RAM. The same thing in a VM costs you a gigabyte before the service even starts. Reach for a VM when you need a different kernel, a different operating system, or hard isolation. Use a container for everything else.

Proxmox hardware requirements: what you actually need

Here is the part that took me the longest to find written down anywhere honestly. Every guide either says “any old PC will do” or shows you somebody’s $3,000 rack.

The floor

An old office desktop is the correct answer for a first server. I build small form factor machines as a hobby and still would not build one for this, because a used business desktop is cheaper than the case alone (my actual PC builds are a separate obsession). A used small form factor business machine with a 4-core chip and 32GB of RAM sits somewhere around $120 to $200 depending on how patient you are, and it will run more than you expect. The two things worth checking before you buy: how many RAM slots it has, and how many SATA ports and drive bays it has. I underbought on drive bays and it has annoyed me for months.

Virtualization extensions need to be on in the BIOS. They frequently ship off. Turn on VT-x or SVM, and while you are in there turn on VT-d or AMD-Vi as well even if you don’t need it yet.

What each service adds

These are the numbers I use for planning. Plan on what you allocate, not what the service idles at. A VM takes its full allocation from the start, and a container can climb to its limit the moment it gets busy.

Add up the ones you want, add 2GB for the host, then add 25% headroom. That’s your RAM number. If it comes to more than your box holds, the fix is almost never a bigger CPU.

Two examples. A media server with Plex, a file share, and a download client comes to about 8GB allocated, which fits comfortably on a 16GB machine. Add Home Assistant, a photo library, and a Windows VM and you are at 26GB, which means 32GB minimum and you will feel it.

The transcoding thing, because everybody asks

If your devices can play your files as they are, video streaming costs almost nothing. Any potato handles four simultaneous direct plays. The CPU only lights up when it has to convert a file on the fly, which happens when the client can’t handle the codec, or when someone is watching over a slow connection.

Software transcoding a 1080p stream needs a serious chunk of CPU. Software transcoding 4K is not a thing you should plan around on a home server, full stop.

Hardware transcoding fixes this and it is the single best reason to care which CPU you buy. Intel Quick Sync is the easy path. A useful line in the sand: chips from roughly 2017 onward handle 10-bit HEVC, which is what most 4K files are. Older chips do H.264 only. I learned that one by buying older, and my server cannot hardware encode HEVC at all. It is fine, because I set every client to direct play and moved on, but I would spend the extra $40 if I were doing it again.

The five things to know before you open Claude

Claude cannot see your machine. Everything it gets wrong, it gets wrong because it filled in a plausible default for something you didn’t tell it. These five are the ones that actually bite.

1. Your subnet, in CIDR. Not “192.168.1.something.” Run ip -4 addr on the box and read the number after the slash. A lot of home networks are not the /24 everyone assumes, and a firewall rule written against the wrong one will quietly cut off machines that should be fine.
2. Your storage layout. What disks exist, what filesystem each one uses, which one holds the boot, and whether any of them have redundancy. Run lsblk and zpool status and paste the output.
3. Whether virtualization extensions are on. grep -c -E 'vmx|svm' /proc/cpuinfo returns 0 if they’re off in BIOS.
4. Your CPU’s video capabilities, if media is anywhere in your plan. Model number is enough.
5. What you are willing to lose. This one is a feeling, not a command. If you have no backups yet, say so, and Claude will design more conservatively.

Spend four minutes gathering these and the quality of everything downstream changes. I’m not being cute about that. It is the difference between a build session and a debugging session.

The prompt to give Claude

Open a new Claude Project so the context survives between sessions, then paste this with your details filled in.

All four prompts in one plain text file: proxmox-claude-prompt.txt. Same content, easier to keep in a tab while you work.

You are a senior infrastructure engineer who specializes in Proxmox VE,
LXC containers, ZFS, and home server security. I am building a home
server and I want you to plan it with me before we touch anything.

MY HARDWARE
- CPU: [MODEL, CORES/THREADS]
- RAM: [TOTAL]
- Disks: [PASTE THE OUTPUT OF lsblk]
- Virtualization extensions: [ON / OFF / UNKNOWN]
- Network: [SUBNET IN CIDR, e.g. 10.0.0.0/24] gateway [GATEWAY IP]

WHAT I WANT TO RUN
[LIST THE SERVICES. Be honest about how many people will use each one.]

WHAT I ALREADY HAVE RUNNING
[LIST ANYTHING, or "nothing, fresh install"]

MY CONSTRAINTS
- Skill level: [BEGINNER / COMFORTABLE IN A TERMINAL / EXPERIENCED]
- Backups: [WHAT EXISTS TODAY, or "none yet"]
- Budget for more hardware: [AMOUNT or "none"]
- Exposure: [LAN ONLY / REMOTE ACCESS NEEDED]

HOW I WANT YOU TO WORK
1. Before proposing anything, tell me the RAM and CPU budget for my
   list and whether my hardware can actually carry it. If it can't,
   tell me what to cut or what to buy.
2. Default to unprivileged LXC containers. Only propose a VM when
   you can name the specific reason a container won't work.
3. Give every container the minimum access it needs. Never bind mount
   a whole storage pool when one directory will do. Say out loud what
   each container can and cannot reach.
4. Every command you give me gets a one-line explanation of what it
   does and what it changes. I am learning this, not just running it.
5. Never assume a default for anything about my system. If you need
   a value I have not given you, ask me for the command that reveals
   it and wait for the output.
6. For anything destructive or hard to undo, give me the rollback
   first and the command second.
7. After anything that writes a file or a config, give me the command
   that proves it worked by reading the content back. "It didn't
   error" is not proof.
8. Assume I will reboot the host at some point. Everything you build
   must survive that on its own.

Start by telling me what you need to know that I haven't given you.
Then give me a build order and the reasoning behind it.

That last instruction matters more than it looks. The build order is where an experienced person earns their money. Storage before containers, network before services, backups before you have anything worth backing up.

Three follow-up prompts

When you’re ready to build a specific thing:

We're building [SERVICE] now. Walk me through it one step at a time.
Give me one command or one action, wait for my output, then react to
what actually came back rather than what you expected. If my output
doesn't match what you predicted, stop and diagnose before continuing.
Do not batch six steps together.

The one-step-at-a-time constraint is the whole trick. Long batched instructions are where things go wrong silently, because step four fails and steps five and six run anyway.

When something is broken:

[SERVICE] is broken. Here is what I expected and what actually happened:
[DESCRIBE]

Before suggesting a fix, give me three commands that would distinguish
between the most likely causes, and tell me what each possible result
would mean. I'll run them and report back. Do not guess at a fix yet.

I use this constantly. Making it name the hypotheses before proposing a solution cuts down enormously on the confident wrong answer that sends you an hour in the wrong direction.

When it’s all working:

Audit what we built. For each container and VM: what can it reach that
it doesn't need, what happens if it is compromised, and what happens if
the host loses power right now. Rank the problems by how bad they are
and how much work the fix is. Be blunt about the ones I'm going to not
want to hear.

Run this one. It’s the prompt that told me four of my containers had no backups and were all sitting on a single drive with no redundancy, which I knew, and had been carefully not thinking about.

Eight things that went wrong

This is the section I actually wanted to write. Everything above is planning. This is what happened.

1. The facts I got confidently wrong

The permissions story up top is the headline example, but the pattern repeated. I described my network’s shape from memory instead of reading it off the machine, and a firewall rule built on that description locked out hosts it had no business touching. Nothing crashed. Nothing errored. Things just stopped answering, which is the worst failure mode there is, because you don’t find out until you go looking.

Claude cannot verify anything you assert about your own hardware. It takes your word for it, builds on top of it, and the mistake surfaces four steps later wearing a disguise. Read values off the box. Paste the actual output. It costs you thirty seconds.

2. ZFS child datasets don’t come along for the ride

I mounted a storage pool into a container and could see the top level fine. The folders inside it, which were separate datasets, showed up empty. Not missing, empty, which sent me looking at permissions for an hour.

Child datasets are separate filesystems. Mounting the parent does not bring them. Mount each dataset you actually need, individually, which turns out to be better practice anyway because it forces you to decide what each container gets to see.

3. Containers that vanish after a reboot

Set onboot: 1 on every container and VM you want to survive a restart. It is not the default. I found out the way everybody finds out, which is that the power blinked and my file server did not come back and I did not notice for two days.

While you’re there, set boot order and delays too. A container that depends on network storage should not start before the thing serving it.

4. Unprivileged containers and the great permissions mystery

The one from the top of the post. Worth restating as a rule, because it will happen to you: in an unprivileged container, every user ID inside is offset by 100000 on the host. User 999 inside is 100999 outside.

The fix is to set ownership on the host side to the mapped ID. Once you know the rule it takes thirty seconds. Before you know the rule it is an afternoon of chmod 777 and shame.

Related trap: files written to a share by a Windows machine land owned by root and become invisible to the service again. I run a small scheduled job that fixes ownership on that directory. Not elegant. Works.

5. Some features have to be turned on from outside

I spent a while trying to get an encrypted filesystem working inside a container, running the enable command inside the container, wondering why the kernel module was there but nothing worked.

That feature is gated at the host level, on the container’s config, and it needs the container restarted. The lesson generalizes: when something inside an unprivileged container refuses to work and the error is about permissions or missing devices, the fix is usually a line in the container’s config file on the host, not anything you can do from inside.

6. “It ran without errors” is not verification

This is my favorite one because it is so quietly awful.

I pushed a shell script to a container, ran a syntax check on it, got a clean result, and moved on. The script was zero bytes. A syntax check passes on an empty file. Nothing had actually transferred, and I spent the next while debugging a script that did not exist.

Now I check the content of everything after writing it. Line count, file size, first few lines, last few lines. Claude will happily tell you a step succeeded because the command returned 0. Make it prove the file says what it should say. I put this in the prompt above for exactly this reason.

7. I tested a safety mechanism on real data

The only data I have actually lost in this whole project, I lost to a thing I had built to protect data.

I wrote an automatic lock for an encrypted volume: idle for ten minutes, lock it. Sensible. What I did not account for was a long file transfer, during which the volume is busy but nobody is typing. It locked mid-copy. I lost a file. It was not an important file, which is pure luck.

The rule I follow now, and I follow it religiously: never test a safety mechanism against anything you care about. Copy in some junk, disarm the mechanism, trigger the condition by hand, watch it behave correctly and watch it behave correctly in the negative case too, then arm it. Every hour that felt wasted doing that is an hour I now consider well spent.

8. The hardware capability I assumed I had

I planned a whole build around splitting my processor’s integrated graphics between virtual machines. Read guides, edited kernel parameters, rebooted a lot. The feature had been removed from modern kernels for my generation of chip years earlier. It was never going to work.

Claude went along with it for longer than it should have, because I framed it as “help me set this up” rather than “should this work.” Ask the second question first. “Does my specific hardware support X on my specific kernel version, and how would I verify that before I start” is a two-minute question that saves a weekend.

The guardrails I’d give anyone

Short list. These are the rules I paste into every server session now.

• Unprivileged containers by default. Justify every exception out loud.
• Minimum access per container. If it doesn’t need your media library, it does not get your media library.
• No service runs as root when a dedicated user will do.
• Verify by reading content back, never by absence of error.
• Rollback plan before destructive commands.
• One step, one output, one reaction. No batches.
• Backups exist before the thing being backed up matters.
• Anything you’d hate to explain to your family gets tested on junk data first.

Proxmox home server FAQ

Should I use Proxmox, TrueNAS, or just Docker on Ubuntu?
Proxmox if you want to run mixed workloads and care about snapshots and isolation. TrueNAS if storage is the point and apps are a bonus. Docker on Ubuntu if you have two or three services and want the least moving parts. There is no wrong answer here, only wrong reasons. Pick the one whose failure mode you’d rather debug at 11pm.

LXC container or VM?
Container unless you need a different kernel, a different operating system, or hard isolation from the host. Containers are enormously cheaper in RAM and start in about a second.

Do I need ECC RAM?
No. It’s better, and if you’re buying used server hardware you may get it for free. But the internet will tell you ZFS demands ECC and that has never been true. Regular RAM plus actual backups beats ECC plus no backups, and it isn’t close.

How much RAM do I really need?
Add up your services from the table above, add 2GB for the host, add 25%. For most people building a first server that lands between 16GB and 32GB. Buy 32GB if the board takes it, because adding RAM later means downtime and you will want it.

Can Claude connect to my server directly?
It can, and I don’t. I read commands, understand them, and paste them myself. That friction is a feature at this stage, because it is the only reason I now understand my own infrastructure. Automate it later, once you’d catch a bad command by reading it.

How long does this take?
Base install, under an hour. A first useful service, an evening. A setup you trust with things you’d be upset to lose, a few weekends and at least one incident you’ll write down and never repeat.

A game server without port forwarding

I used to keep a separate write-up on running a Minecraft server this way. It now lives here, because the pattern is the useful part and it applies to any service you want to share with one person.

Every guide says to forward port 25565 on your router. I did not want to do that, and most people should not either. Forwarding a port puts a service on the public internet, and automated scanners find it within hours. A game server is a large pile of code parsing untrusted input from strangers. For something only two people will ever use, that is a bad trade.

The pattern instead: install a mesh VPN inside the container, not on the host. Share exactly that one machine with the person you play with, and restrict them by policy to one TCP port. Set the policy before you connect the VPN, because tagging a machine requires the tag to exist in policy first. A new account ships with a permissive allow-everything default. Replace it with two rules: one that lets your own devices reach everything so you do not lock yourself out, and one that lets shared users reach only the game port on the tagged machine.

What you get: port 25565 stays closed on your router, the only thing the VPN opens is an outbound connection your router already allows, and your friend can reach one port on one container. Not your files, not your other machines, not even SSH on that container. It runs fine in an unprivileged LXC with 4GB of RAM and two cores for a handful of players, and it costs nothing.

Three traps. Machine keys expire in 180 days unless you tag them, and an expired key drops the server off the network with no warning. Do not use bind mounts; the most important line in the whole build is the one you do not write. And add the container to a scheduled backup job before anyone builds a world they would be upset to lose.

Keep reading: the rest of the homelab series

This guide is the overview. Each of these goes deep on one thing that cost me real time.

• Unprivileged LXC permissions, the 100000 offset from the opening of this post, written up properly as a reference.
• Plex hardware transcoding, why direct play is free, and how to pass an integrated GPU into a container.
• Plex in an LXC, start to finish, the container itself: create it, mount the media, install Plex, fix ownership, claim it.
• LXC versus VM, a decision table and the three months I spent on the wrong side of it.
• A backup strategy, written after I noticed I did not have one.

What I’d tell myself six months ago

Gather the five facts before you ask for anything. Read every command before you paste it. Check the file says what it should say. Build the backup job before you build the thing you’d hate to lose.

None of that is clever. It is just the stuff that separates a weekend of building from a weekend of debugging, and I had to learn all of it the expensive way so that you can read it in a table.

I still like this hobby, for the record. There is something genuinely good about opening a laptop in a hotel and watching a machine in my house do exactly what I told it to six months ago.

If you want to see the same approach pointed somewhere else, I wrote up how I handed Claude the keys to this website. Same idea underneath: a written playbook, revocable access, and guardrails decided before you need them. My other builds live on the projects page, and when something on the server breaks in an interesting way I write it up in the newsletter.