Run Deployrr in a Proxmox LXC container
This guide is for you if Deployrr runs, or will run, in an LXC container on Proxmox. It covers creating the container, the System Type choice, the network device VPN apps need, USB sticks, NAS storage, Kasm, and when a virtual machine is the better choice.
Overview
Section titled “Overview”Deployrr has no menu that changes Proxmox settings. Anything that happens on the Proxmox host, you do by hand. Deployrr only checks what the container gives it and tells you what is missing.
You will:
- Create a container that suits Deployrr, if you don’t have one yet.
- Set System Type to match your container.
- Pass
/dev/net/tuninto the container, if you use VPN apps, and a USB stick, if an app needs one. - Give the container your NAS files with a bind mount or Rclone.
- Know the limits for Kasm, GPU and Docker.
Create a container that suits Deployrr
Section titled “Create a container that suits Deployrr”Deployrr doesn’t create the container and doesn’t check its size. You make these choices in Proxmox’s Create CT wizard. The Proxmox steps are general Proxmox knowledge, not a Deployrr feature.
Unprivileged or privileged
Section titled “Unprivileged or privileged”Pick Unprivileged unless you need Kasm. It is the safer choice: a process that breaks out of an unprivileged container has much less power on the Proxmox host. The choice changes three things in Deployrr:
| Unprivileged LXC | Privileged LXC | |
|---|---|---|
| Socket Proxy | Runs without extra privileges | Gets extra privileges |
| Kasm | Can’t install | Needs the workaround for now |
| NAS files in a bind mount | Show as nobody until you fix the owner |
Keep their owner |
You can’t switch a container between the two in place. If you need the other type later, create a new container and move Deployrr to it. See Move Deployrr to a new server.
Settings in the Create CT wizard
Section titled “Settings in the Create CT wizard”- General: keep Unprivileged container ticked for an unprivileged container. Tick Nesting. Docker runs containers inside your container, and it needs nesting to do that.
- Template: pick Ubuntu 22.04 or newer, or Debian 11 or newer. Download the template in your storage’s CT Templates first. See Supported systems.
- Disks: Docker images, app data and logs live on this disk. If your media stays on a NAS, 64 GB is a good start. Make it larger if downloads or the metadata for a big media library stay in the container.
- CPU and Memory: Deployrr has no minimum. Size them for the apps you plan to run, and leave some for the Proxmox host. The video below uses 4 cores, 8 GB of memory and 4 GB of swap for a test container. A media server with many apps needs more. You can raise these later in the container’s Resources.
- Network: set a static IP address here, not inside the container. See Proxmox LXC and VM.
To watch an unprivileged container created for Docker, with nesting, disk, cores and memory, see Docker on Proxmox LXC: creating the container at 4:10.
After the container starts:
- Log in and create a regular Linux user that can run
sudo. Deployrr doesn’t run as root. See Prerequisites. - If you plan to use VPN apps, add
/dev/net/tunnow. See Pass /dev/net/tun into the container. - If you plan to use Rclone for NAS shares, turn on FUSE now. See Turn on FUSE for Rclone.
- Install Deployrr. See Quick start.
Choose your System Type
Section titled “Choose your System Type”System Type is a step in Prerequisites. It opens Pick your System Type. Choose the option that matches where Deployrr runs, then select Select. You see System Type Configured with “SUCCESS: System type set to” and your choice. Skip leaves the old value.
| Choice | Use it when |
|---|---|
| Unprivileged LXC | Deployrr runs in an unprivileged LXC container on Proxmox. |
| Privileged LXC | Deployrr runs in a privileged LXC container on Proxmox. |
| Virtual Machine | Deployrr runs in a VM on any hypervisor, such as Proxmox, WSL, ESXi or VirtualBox. |
| Barebones | Linux runs directly on the hardware. |
| VPS | Linux runs on a virtual private server in the cloud. |
To see how a VM, a privileged LXC and an unprivileged LXC differ, watch Docker on Proxmox LXC: LXC vs VM and privileged vs unprivileged at 1:45.
You must set System Type before Prerequisites counts as complete. You can run it again at any time. See System Type in Prerequisites.
The choice changes these things:
- Socket Proxy. When you install Socket Proxy, Deployrr gives it extra privileges on every System Type except Unprivileged LXC. In an unprivileged LXC it stays off. The choice applies when you install. If you change System Type later, reinstall Socket Proxy from Docker > Socket Proxy so it applies. See Socket Proxy.
- SMB Mount and NFS Mount. They only work on VPS, Barebones and Virtual Machine. See Add NAS storage.
- Kasm. See Kasm.
Pass /dev/net/tun into the container
Section titled “Pass /dev/net/tun into the container”VPN apps need the /dev/net/tun network device. This covers qBittorrent VPN with Gluetun, Tailscale, ZeroTier and Cloudflare Tunnel. A new LXC container does not have it. You add it on the Proxmox host. This is general Proxmox knowledge, not a Deployrr feature.
In System > Network, Deployrr first shows a Network Adapter box that says VPN apps need the device at /dev/net/tun. Then it shows “Network Adapter Detection”. It checks /dev/net/tun and the permissions of your user. It saves the result. The menu only changes when you run it again.
Replace ID with your container’s number, such as 101. Run these commands on the Proxmox host, not in the container.
-
Stop the container:
Terminal window pct stop ID -
Back up the config file:
Terminal window cp /etc/pve/lxc/ID.conf /root/ID.conf.before-tun -
Open the file:
Terminal window nano /etc/pve/lxc/ID.conf -
Add these two lines at the end, then save:
lxc.cgroup2.devices.allow: c 10:200 rwmlxc.mount.entry: /dev/net/tun dev/net/tun none bind,create=file -
Start the container:
Terminal window pct start ID -
Inside the container, check that the device exists:
Terminal window ls -l /dev/net/tunThe line must start with
c, for examplecrw-rw-rw-. That means it is a character device. -
In Deployrr, open System > Network and run it again.
If the container does not start, restore your copy on the Proxmox host and start it again:
cp /root/ID.conf.before-tun /etc/pve/lxc/ID.confpct start IDNewer Proxmox versions can also add a device in the web UI under the container’s Resources. Use /dev/net/tun as the path. The config lines above work on any version.
To see the config lines added on a Proxmox host, watch Proxmox LXC network device passthrough at 2:53. For the same steps in writing, read UDMS part 10 (manual setup).
What the result means
Section titled “What the result means”| What you see | What it means |
|---|---|
Network adapter device found at /dev/net/tun, then Device is readable and writable by YOUR_USER, then Network adapter detection completed - VPN support enabled |
Done. |
No network adapter detected at /dev/net/tun and Network adapter detection completed - No adapter detected |
The device is not in the container. Check the two config lines and restart the container. |
Device is not readable or writable by YOUR_USER and Network adapter detection failed - Permission issue detected |
The device is there, but your Linux user can’t use it. The device must be readable and writable by your user. Check its permissions with ls -l /dev/net/tun inside the container. |
For the apps that use this, see qBittorrent VPN and Tailscale.
Pass a USB stick into the container
Section titled “Pass a USB stick into the container”A Zigbee or Z-Wave stick must reach the LXC before Docker can hand it to an app such as Home Assistant. You do this on the Proxmox host. This is general Proxmox knowledge, not a Deployrr feature.
-
Plug the stick into the Proxmox host.
-
On the host, list the stable device names:
Terminal window ls -l /dev/serial/by-id/Copy the full path of your stick, such as
/dev/serial/by-id/usb-YOUR_STICK_NAME. This name stays the same after a reboot. A name like/dev/ttyUSB0or/dev/ttyACM0can change. -
In the Proxmox web interface, select your container, then Resources > Add > Device Passthrough.
-
Set the device path to the path from step 2.
-
Restart the container.
-
Inside the container, check the device:
Terminal window ls -l /dev/serial/by-id/You should see your stick at the path you entered. If the folder is empty or missing, look for a short device name too:
Terminal window ls -l /dev/ttyUSB* /dev/ttyACM*An error for one of the two names is normal. If neither command shows the stick, check the path you entered in step 4 and that the stick is plugged into the host.
-
In the app’s Compose
devices:line, use the path the stick has inside the container. For Home Assistant, see Add a Zigbee or Z-Wave USB stick.
The GID field in Device Passthrough sets the group of the device inside the container. Leave it empty unless the app can’t open the stick. Then set it to the group ID of the dialout group inside the container. To find it, run getent group dialout inside the container. The number after the second colon is the GID.
If your Proxmox has no Device Passthrough entry under Add, update Proxmox first.
Add NAS storage
Section titled “Add NAS storage”In an LXC container, open System > Mounts > SMB Mount or NFS Mount and choose Yes at the setup question. You then see “Not Supported”. The text says: “SMB mounting is only supported on VPS, Barebones, or Virtual Machine systems. If you are using a Proxmox LXC, then use Bind Mounts or Rclone.” NFS Mount shows the same text for NFS.
You have two choices:
- Rclone. Deployrr does not block it in an LXC, and it works once FUSE is turned on for the container. See Turn on FUSE for Rclone below, then Mount a NAS share with Rclone.
- A Proxmox bind mount. Mount the NAS on the Proxmox host, then share that folder with the container. The bind mount steps below are general Proxmox knowledge.
Turn on FUSE for Rclone
Section titled “Turn on FUSE for Rclone”Rclone mounts your share through FUSE. An LXC container can’t use FUSE until you turn it on from the Proxmox host. Do this before you run Install in the Rclone menu:
- In the Proxmox web interface, select the container.
- Open Options, select Features, then select Edit.
- Tick FUSE and select OK. Leave the features that are already ticked as they are.
- Restart the container.
Deployrr does the rest inside the container when you run Install: it installs fuse3 and lets your apps read the mounted files.
To see this setting in Proxmox, watch Rclone SMB mount on Ubuntu/LXC: Proxmox LXC modifications at 3:29 (manual Docker Compose setup). The video also adds an extra disk for the Rclone cache. You don’t need it.
If Automount ends with “Mount verification failed”, check that FUSE is ticked for the container, then read the Rclone log as shown in Mount a NAS share with Rclone.
Bind mount a folder into the container
Section titled “Bind mount a folder into the container”To understand how bind mounts and ID mapping work, read UDMS part 9: How Proxmox bind mounting works (manual setup).
This works for a NAS share mounted on the Proxmox host, or for a local disk. Replace these values:
IDis your container’s number./mnt/host-folderis the folder on the Proxmox host./mnt/mediais the path you want inside the container.
-
On the Proxmox host, list the mount points the container already has:
Terminal window pct config ID | grep '^mp'pct setreplaces a mount point with the same number. Ifmp0is in the list, use the next free number, such asmp1, in the next command. -
Add the bind mount:
Terminal window pct set ID -mp0 /mnt/host-folder,mp=/mnt/media -
Restart the container:
Terminal window pct reboot ID -
Inside the container, list the folder:
Terminal window ls -l /mnt/mediaYou should see your files.
-
In Deployrr, open System > Folders and set your media or downloads folder to
/mnt/media. See Set your media, downloads and other folders.
Files show as nobody in an unprivileged LXC
Section titled “Files show as nobody in an unprivileged LXC”In an unprivileged LXC, Proxmox shifts user IDs by 100000. A file owned by UID 1000 on the host shows as nobody (UID 65534) inside the container. Your user can’t write to it.
The simplest fix is to make the host folder belong to the shifted IDs.
-
Inside the container, find your user’s IDs:
Terminal window idIf your user is
1000:1000, the host IDs are101000:101000. Add 100000 to your own numbers if they differ. -
On the Proxmox host, change the owner. Replace
/mnt/host-folderwith your folder.Terminal window chown -R 101000:101000 /mnt/host-folder
Kasm can’t install on an Unprivileged LXC. The install stops with “System type not compatible”, then “[REQUIRED] Compatible with:” and “[CURRENT] Your system:”. Use a VM or a VPS for Kasm.
Right now Kasm may stop with the same message on Virtual Machine, Privileged LXC and Barebones too. Only VPS passes. If you run a Privileged LXC, a VM or a bare-metal server, this workaround gets you through:
- Open Prerequisites > System Type and select VPS.
- Install Kasm.
- Open System Type again and set it back to your real type.
Set it back right away. Deployrr reads System Type when you install Socket Proxy or Kasm, and when you open SMB Mount or NFS Mount. Don’t install or reinstall Socket Proxy while it is set to VPS.
GPU and Docker problems
Section titled “GPU and Docker problems”- The System > GPU box says “LXC/Docker environments require the host to pass through the GPU device and toolkits.” Do the pass-through on the Proxmox host first. See Prepare your server’s GPU. Then see GPU hardware transcoding.
- If Docker stops starting containers after an update with “failed to create shim task”, see Docker fails with “failed to create shim task”.
When a VM is the better choice
Section titled “When a VM is the better choice”An LXC shares the Proxmox host’s kernel. That makes it light, but you work around its limits by hand. Pick a virtual machine if you want to avoid that. A VM has its own kernel, so you don’t pass devices by hand for VPN apps, and SMB Mount and NFS Mount work. Set System Type to Virtual Machine. For Kasm in a VM, see the workaround in Kasm. The cost is more memory and disk use than an LXC. For background, read UDMS part 3: when to choose a VM instead (manual setup).
Move Deployrr from an LXC to a VM
Section titled “Move Deployrr from an LXC to a VM”You can’t convert a container into a VM. You move Deployrr with a Migration Package. It needs a Pro license on both servers. Without Pro, there is no Deployrr tool for this move. Ask in Discord.
The package holds your Docker folder and Deployrr’s settings. It holds nothing outside the Docker folder, so NAS folders you bind mounted into the LXC are not in it.
- In Proxmox, create the VM and give it a static IP. See Proxmox LXC and VM.
- Create the same Linux user name the LXC uses, then install Deployrr in the VM. See Quick start.
- In the LXC, open Tools > Backups > MP Create. At the restart question, press any key other than
Y. Don’t run the same apps on both servers at once. - Copy the package to the VM, then run MP Restore there. The restore puts the Docker folder back at the same path it had in the LXC. At “Deployrr will now restart”, press
Y. For these steps, see Move Deployrr to a new server. - In Prerequisites, choose System Type and select Virtual Machine. The restore brings back the old setting, so the VM still says an LXC type until you change it.
- Mount your NAS shares with System > Mounts > SMB Mount or NFS Mount. Use the same path the LXC used, such as
/mnt/media, so your apps’ folder paths still match. See SMB and NFS mounts. - Follow Fix up the new server. Run System Checks and Domain Checks again. If the VM’s IP differs from the LXC’s, run Tools > Change Server IP and enter the VM’s IP, then the LXC’s old IP. If the hostname differs, run Tools > Change Hostname. Then start your apps with Tools > Stack Manager > Up.
- Shut down the LXC.
In a VM, you don’t need the /dev/net/tun lines or the LXC USB steps. To give a USB stick to a VM, open the VM in Proxmox, then Hardware > Add > USB Device. For a GPU, see Prepare your server’s GPU.
Check it worked
Section titled “Check it worked”- System Type shows “
is on - ” in Prerequisites. - System > Network ends with “VPN support enabled”.
ls -l /dev/serial/by-id/orls -l /dev/ttyUSB* /dev/ttyACM*inside the container shows your USB stick, if you passed one.ls /mnt/mediainside the container shows your NAS files.
Next steps
Section titled “Next steps”- Install qBittorrent VPN: qBittorrent VPN.
- Set up Tailscale: Tailscale.

