DEV Community

爱国者
爱国者

Posted on AI-assisted

Run a file browser for your whole LAN with one binary (no Docker, no database)

I keep a small box in the corner of the room with two disks attached. For years the only way to use it from a phone was a Samba share and an app that could not preview anything. Now it runs a single Go binary that serves a browser UI, and any device on the network - phone, tablet, TV, laptop - can browse and preview files with nothing installed.

This is the practical version of that setup. Roughly 15 minutes, one file, no Docker, no database, no PHP, no cron.

What you need

  • A machine on the same network as your files: a Raspberry Pi (4 or 5), a mini PC, an old laptop, or the NAS itself if it can run a Linux binary.
  • Ports: one HTTP port for the UI. Pick something unused, e.g. 8688.
  • Optional: a reverse proxy with TLS if you want to reach it from outside.

Supported builds include Windows, macOS, Linux (amd64/arm64/armv7), FreeBSD, and an Android APK.

1. Get the binary

Download the build for your platform from the release directory and drop it anywhere - there is no installer:

mkdir -p ~/banyan && cd ~/banyan
# arm64 Linux (Pi 4/5, most ARM mini PCs)
curl -LO https://banyan.ikootoo.com/release/20261118/banyan-linux-arm64
chmod +x banyan-linux-arm64
mv banyan-linux-arm64 banyan
Enter fullscreen mode Exit fullscreen mode

On Windows it is the same idea: put one .exe in a folder and double-click it.

2. Run it headless

./banyan -headless
Enter fullscreen mode Exit fullscreen mode

It prints a listening address. Open that address from any browser on the LAN and you have the file browser: a folder tree on the left, a thumbnail grid on the right.

If you want it to survive SSH logout, run it under systemd:

# /etc/systemd/system/banyan.service
[Unit]
Description=Banyan file browser
After=network.target

[Service]
ExecStart=/home/pi/banyan/banyan -headless
WorkingDirectory=/home/pi/banyan
Restart=always
User=pi

[Install]
WantedBy=multi-user.target
Enter fullscreen mode Exit fullscreen mode
sudo systemctl enable --now banyan
Enter fullscreen mode Exit fullscreen mode

3. Point it at your disks

Mount the disks with the OS, not with the app - /etc/fstab or systemd mount units. Then add the folder you want to expose as a root. Keeping the mount and the file browser separate means a failed disk does not take the UI down with it, and you can move the folder later without reconfiguring anything inside the app.

A detail worth knowing: the preview pipeline runs on the machine that holds the files. When you tap a 60 MB RAW photo on a phone, the server renders a thumbnail and sends a few hundred KB. That is the whole reason this works over a weak Wi-Fi link.

4. Keep it off the internet (unless you mean it)

The binary binds to an interface you choose. Bind to the LAN address only, and do not port-forward it. For remote access, put a VPN or a TLS reverse proxy in front:

files.example.com {
    reverse_proxy 127.0.0.1:8688
}
Enter fullscreen mode Exit fullscreen mode

Inside the app there are no user accounts and no ACLs - by design. Permissions are the OS's job, and sharing is a link with an expiry. That is a smaller attack surface than a login form nobody rotates.

5. Share a folder without creating an account

Share links carry a token and an expiry date. Send the client a URL, they open it in a browser, and it stops working when the date passes. No signup, no guest account to clean up later.

6. What you get beyond thumbnails

  • Previews for 100+ formats: HEIC, RAW, PDF, Office documents, archives, subtitles, fonts.
  • Video and audio playback with range requests, so seeking works.
  • Editing inside the preview - fix a typo, crop a photo - and it writes back to the same path. No download-edit-upload loop.
  • PDF watermark and signature stamping.
  • Per-directory AES-256-GCM encryption.
  • Drag-and-drop upload that preserves the folder structure.

Practical notes from running this for a while

  • Battery-backed box, not a laptop lid. An old laptop that sleeps when closed is the most common reason a self-hosted file browser "stops working". Disable sleep or use a Pi.
  • Use one disk mount per folder. Two mounts nested inside each other produce confusing trees.
  • Do not fight the missing sync. This is a browser, not a sync client. If you need offline edits that merge back, that is a different product (Nextcloud, Seafile).
  • Check the port first. ss -lntp | grep 8688 before blaming the app.

That is the whole deployment: one file, one service, one port, no stack to keep patched.

Site: https://banyan.ikootoo.com/
Code: https://github.com/nbmany-web/banyan (MIT)
Builds: https://banyan.ikootoo.com/release/

Top comments (0)