File Browser — the little Go program that gave thousands of homelabs a simple web UI for browsing, uploading, and sharing files — is being shut down. The maintainer announced the project's archival for September 1, 2026, and made it clear that any security issues found after that date won't be patched. If you've got File Browser running on your Proxmox VE box right now, that's worth paying attention to.
The good news is that the project didn't just vanish. A fork called FileBrowser Quantum picked up where the original left off, rewrote a good chunk of the backend, and added things like multiple file sources, LDAP and OIDC login, and two-factor authentication. It's the closest thing to a direct successor, and it's actively maintained. This guide walks through installing it in a lightweight LXC container on Proxmox VE, from creating the container to logging into your new file manager for the first time.
What You Will Learn
- Why the original File Browser project is being retired and what that means if you're already running it
- How to create a small Debian LXC container on Proxmox VE for FileBrowser Quantum
- How to download the binary, write a working
config.yaml, and run it as a systemd service - Where to find the randomly generated admin password on first login
- The specific mistakes that trip people up on their first install, and how to fix them
What Is FileBrowser Quantum?
FileBrowser Quantum is a self-hosted web application that gives you a browser-based file manager for a folder (or several folders) on a Linux server. Think of it as a private, lightweight alternative to the web interface you get with Nextcloud or Google Drive, minus the calendar, contacts, and office-suite features. You point it at a directory, and it hands you a clean web UI for uploading, downloading, renaming, previewing, and sharing files.
It's a fork of the original File Browser project, maintained by a different developer (gtsteffaniak on GitHub) under the name FileBrowser Quantum. Version 2.0 rewrote the storage layer to use SQLite instead of the old embedded BoltDB, and added support for indexing multiple folders at once, external authentication (LDAP, OIDC), and role-based sharing. If you've used the original File Browser before, the interface will feel familiar, but the configuration file has changed shape entirely.
One term worth clearing up before we go further: an LXC container is Proxmox VE's lightweight alternative to a full virtual machine. Instead of emulating hardware and booting a separate kernel, it shares the host's kernel and just isolates a set of processes, similar to how Docker containers work, but closer to a full Linux system with its own users and services. For something as small as a file manager, an LXC container is a better fit than a VM — it starts in about a second and uses a fraction of the RAM.
Why Would You Use It?
Most Proxmox VE homelabs end up with files scattered across a few places: backup ISOs on one storage pool, downloaded media on another, project files on a third. FileBrowser Quantum doesn't replace proper storage like ZFS or NFS — it sits on top of a folder and gives you a way to get at those files from a phone or laptop without SSH, SCP, or mounting a network share every time.
It's also a reasonable choice if you were already running the original File Browser and don't want to be stuck on unmaintained software with public, unpatched vulnerabilities after September 2026. Migrating means standing up a new instance rather than upgrading in place, which is exactly what this guide covers.
Compared to Nextcloud, which needs PHP, a database server, and a fair amount of RAM, FileBrowser Quantum is a single static binary with an embedded SQLite database. No package manager dependencies to fight with, no PHP version mismatches. That simplicity is the whole appeal. If you need sync clients, calendar and contacts, or multi-user collaboration with sharing permissions across a team, Nextcloud is still the better tool. If you just want a fast web UI to poke at files on your server, this is lighter and quicker to stand up.
| Tool | Best for | Resource footprint |
|---|---|---|
| FileBrowser Quantum | Quick browser access to a folder, single binary, no database server | Very low (single Go binary + SQLite) |
| Nextcloud | Full cloud storage suite with sync clients, sharing, calendar | Higher (PHP, MySQL, background jobs) |
| Samba share | Native file browsing from Windows/Mac Explorer, no web UI | Very low, but no web access |
Prerequisites
Before you start, make sure you've got the following:
- A working Proxmox VE host — this guide was written against Proxmox VE 9.x, but the container creation steps work the same on 8.x
- A Debian 12 (Bookworm) LXC template downloaded, or access to
pveamto download one - At least 512 MB of RAM and 2 GB of free disk space on the storage you'll use for the container's root filesystem
- Basic comfort with a Linux shell — you'll be typing commands inside the container, not clicking through a GUI installer
- A folder of files you actually want to browse. If you don't have one yet, we'll create an empty one to start with
Step-by-Step Tutorial
Step 1: Create the LXC container
Log into the Proxmox VE web interface, or SSH into the host directly. If you're doing this from the shell, make sure the Debian 12 template is available:
pveam update
pveam available | grep debian-12
pveam download local debian-12-standard_12.7-1_amd64.tar.zstThe exact filename after debian-12-standard changes as Proxmox refreshes the template, so double-check what pveam available actually lists before copying that download command verbatim.
Now create the container. Pick an unused VMID — this example uses 115:
pct create 115 local:vztmpl/debian-12-standard_12.7-1_amd64.tar.zst \
--hostname filebrowser \
--cores 1 \
--memory 512 \
--swap 512 \
--rootfs local-lvm:4 \
--net0 name=eth0,bridge=vmbr0,ip=dhcp \
--unprivileged 1 \
--onboot 1One core and 512 MB of RAM is genuinely enough here — FileBrowser Quantum is not a heavy program. Four gigabytes of disk gives you room for the OS, the binary, and a reasonable SQLite database; it's not where your actual files live, since those stay on whatever storage you point the config at.
Start the container and drop into its console:
pct start 115
pct enter 115Step 2: Update the container and install basics
You're now inside the container's shell. Update the package list and grab a couple of tools you'll need:
apt update && apt full-upgrade -y
apt install -y curl wget nanoThis takes a minute or two on a fresh template. Don't skip it — some Debian 12 template builds are a few months stale, and installing wget on an unpatched system is a bad habit to start with.
Step 3: Download the FileBrowser Quantum binary
FileBrowser Quantum ships as a single static binary from its GitHub releases page. Grab the latest amd64 build:
mkdir -p /opt/filebrowser
cd /opt/filebrowser
wget https://github.com/gtsteffaniak/filebrowser/releases/latest/download/filebrowser-linux-amd64 -O filebrowser
chmod +x filebrowser
mv filebrowser /usr/local/bin/filebrowserIf your container is running on ARM hardware (a Raspberry Pi host, an Apple Silicon Mac under UTM, that kind of thing), swap filebrowser-linux-amd64 for the matching arm64 asset name from the same releases page. Everything else in this guide stays the same.
Step 4: Create a folder to serve and a config file
Decide where your files will actually live. For this example we'll use /srv/files:
mkdir -p /srv/filesNow write the config file. This is the part people get wrong most often, so read the note right after it before you save.
nano /opt/filebrowser/config.yamlserver:
port: 8080
sources:
- path: "/srv/files"
config:
defaultEnabled: true
auth:
adminUsername: adminTwo things worth calling out. First, we're using port 8080 instead of the default port 80 shown in the official docs — ports below 1024 need root privileges to bind, and running FileBrowser Quantum as root just to grab port 80 is more risk than it's worth for a homelab tool. Second, the official documentation is explicit that you should never point path at your root filesystem (/) or at /var. Doing so exposes system files through the web UI, which is exactly the kind of mistake that turns a convenience tool into a security incident.
Step 5: Create a dedicated system user
Running FileBrowser Quantum as root isn't necessary and isn't a good idea. Create a system account with no login shell:
useradd -r -s /usr/sbin/nologin filebrowser
chown -R filebrowser:filebrowser /opt/filebrowser /srv/filesStep 6: Set up the systemd service
Create the unit file:
nano /etc/systemd/system/filebrowser.service[Unit]
Description=FileBrowser Quantum
After=network.target
[Service]
Type=simple
User=filebrowser
WorkingDirectory=/opt/filebrowser
ExecStart=/usr/local/bin/filebrowser -c /opt/filebrowser/config.yaml
Restart=on-failure
[Install]
WantedBy=multi-user.targetReload systemd and start the service:
systemctl daemon-reload
systemctl enable --now filebrowserStep 7: Find your admin password and log in
Because we only set adminUsername in the config and not a password, FileBrowser Quantum generates a random one on its very first run and writes it to the service log. This only happens once, so grab it now:
journalctl -u filebrowser -n 50 --no-pagerLook for a line mentioning the generated password for the admin user — copy it somewhere safe before you do anything else. If you restart the service before saving it and never change it in the UI, you'll need to reset the admin account through the CLI, which is more work than copying a line out of a log.
Find the container's IP address if you don't already have it:
pct exec 115 -- ip a show eth0Then open http://<container-ip>:8080 in a browser, log in with admin and the password from the log, and change that password immediately from the settings page. Treat the generated one as temporary from the moment you see it.
Commands Explained
| Command | What it does |
|---|---|
pveam update | Refreshes the list of LXC templates Proxmox VE knows how to download |
pct create | Builds a new LXC container from a template with the resources and network settings you specify |
pct enter 115 | Drops you into an interactive shell inside container 115, as if you'd SSH'd in |
chmod +x filebrowser | Marks the downloaded binary as executable so Linux will actually run it |
useradd -r -s /usr/sbin/nologin filebrowser | Creates a system account that can own files and run the service, but can't be used to log in interactively |
systemctl enable --now filebrowser | Starts the service immediately and also sets it to start automatically on every container boot |
journalctl -u filebrowser -n 50 --no-pager | Shows the last 50 log lines for the filebrowser service without paging through less |
Common Errors
"bind: permission denied" on startup. You left port: 80 in the config and the service is running as the unprivileged filebrowser user. Either switch to a port above 1024 (what this guide does) or grant the binary the specific capability to bind low ports with setcap 'cap_net_bind_service=+ep' /usr/local/bin/filebrowser.
Config file not found. Usually means the systemd unit's ExecStart line points to a path that doesn't match where you actually saved config.yaml. Double-check both paths match exactly, including the filename.
Can't find the generated password. If the service has been restarted since the first run, that log line is gone for good, and the password won't regenerate itself. You'll need to stop the service, reset the admin account with the CLI's user management commands, and start it again.
Empty file list after logging in. Almost always a path typo in config.yaml, or the filebrowser user doesn't have read permission on the folder you pointed it at. Recheck the chown step above.
Troubleshooting
Start by checking whether the service is even running:
systemctl status filebrowserIf it shows as failed, the journal will almost always tell you why:
journalctl -u filebrowser -eIf the service is running but the page won't load in your browser, confirm you're hitting the right port and that nothing else in the container is already bound to it:
ss -tulpn | grep 8080And if you're connecting from another machine on your network and getting a connection refused rather than a timeout, check that the container's firewall (if you enabled one in the Proxmox VE Firewall tab) actually allows inbound traffic on port 8080. LXC containers don't have a firewall enabled by default, but if you turned one on at the datacenter or container level earlier, it's worth ruling out.
Best Practices
Change the admin password the moment you log in for the first time — don't leave the generated one active longer than it takes to open the settings page. If you're exposing this outside your home network, put it behind a reverse proxy with TLS rather than opening port 8080 directly to the internet; Nginx Proxy Manager is a common pairing for exactly this.
Back up /opt/filebrowser/filebrowser.sqlite along with your actual files. It holds your user accounts, sharing links, and settings, and it's easy to forget because it's not the folder you're actively working in. A simple vzdump backup of the whole container covers this automatically, which is one more reason to run this in its own LXC container rather than bolting it onto something else.
Don't run the service as root. It's tempting to skip the dedicated user step to save five minutes, but a file manager that can read and write anything on the system is a much bigger blast radius if something in it ever gets compromised.
Frequently Asked Questions
Is FileBrowser Quantum a drop-in replacement for the original File Browser?
Not quite. The configuration format changed and the database moved from BoltDB to SQLite in version 2.0, so you can't just point it at your old data folder and expect it to work. You'll set it up fresh, then copy your actual files over.
Do I need to keep the original File Browser running until it's archived?
No. There's no reason to wait until September 1, 2026 to migrate. Set up FileBrowser Quantum now, confirm it works the way you need, then decommission the old container.
Can I run this in a VM instead of an LXC container?
Yes, nothing about FileBrowser Quantum requires LXC specifically. A container just uses less RAM and disk for something this small, and it starts almost instantly.
Does it support multiple user accounts?
Yes, along with LDAP and OIDC authentication if you already run an identity provider like Authentik. For a single-user homelab setup, the built-in admin account plus password auth is usually all you need.
What happens to my data if I stop the service?
Nothing. Stopping or restarting the systemd service doesn't touch the files in your source folder or the SQLite database — it just stops serving the web UI until you start it again.
Conclusion
Migrating off unmaintained software before it becomes a liability is a fairly rare case of good timing lining up with a genuinely useful tool. FileBrowser Quantum isn't a complicated install — a small LXC container, one binary, a short config file, and a systemd unit gets you a working file manager in about ten minutes. Grab that generated password from the log before you forget, change it right away, and you've got a lightweight alternative to digging through SCP commands every time you need a file off your server.