Linux binary setup

One-line option

The optional sponsor bootstrap installs the supported system packages, downloads the matching CPU build and runs setup plus diagnostics:

curl -fsSL https://raw.githubusercontent.com/debridmediamanager/zurg-site/main/public/install.sh | bash

It signs in through GitHub and keeps the install in ~/zurg. Existing binaries and configs are preserved. Continue below for the manual route or a custom path.

The zurg binary can build the rest of its install itself. It writes the config, downloads the correct rclone and ffprobe binaries for the machine, creates the mount and registers an enabled systemd service.

This flow was verified on 4 September 2026 on fresh Ubuntu 24.04 ARM64 and x86_64 servers.

1. Install FUSE 3

On Debian, Ubuntu and their derivatives:

sudo apt-get update
sudo apt-get install -y fuse3

Check that the helper and device are present:

command -v fusermount3
test -c /dev/fuse

If Plex, Jellyfin or another process runs as a different Unix user, enable allow_other once:

echo user_allow_other | sudo tee -a /etc/fuse.conf

Without that setting the mount still works, but only the account running zurg can open it. zurg doctor reports the difference.

2. Download zurg

Download the matching Linux archive from the sponsor releases. Choose linux-amd64 for an Intel or AMD machine and linux-arm64 for an ARM machine.

Take the newest nightly. It is the pre-release at the top of the list. Do not take the release GitHub marks Latest. That is v1.0.0. It is older than zurg setup and answers it with unknown command.

Nightlies are for sponsors. Until your GitHub account has access that page answers 404. The free public build is v1.0.0 from zurg-public. It has no zurg setup. Set it up by hand as its README explains instead of following the steps below.

Extract it into the directory that should hold the whole install:

mkdir -p ~/zurg
cd ~/zurg
# Put the downloaded zurg binary here, then:
chmod +x zurg

Everything zurg keeps stays beside that binary: config.yml, downloaded helpers, library state, logs and the rclone cache.

3. Run setup

cd ~/zurg
./zurg setup

Setup asks which providers to configure. Choose one or several in priority order:

  1) Real-Debrid
  2) TorBox
  3) AllDebrid
  4) Usenet (NZB)

For example enter 2,4 for TorBox followed by Usenet. Setup asks only for the selected credentials. It then:

Creates and validates config.yml.
Restricts the config to its owner with mode 0600.
Downloads native rclone and ffprobe binaries into bin/.
Enables the rclone mount at /mnt/zurg.
Installs and starts an enabled systemd service.

Use a mount inside your home directory when you do not have permission to create /mnt/zurg:

./zurg setup --mount-path "$HOME/zurg-mount"

Setup is safe to run again. It updates the generated service but does not replace an existing config.yml.

Choosing the systemd scope

With a working systemd user manager the default auto scope installs ~/.config/systemd/user/zurg.service. Otherwise setup installs /etc/systemd/system/zurg.service and asks sudo to run it as the current user.

Choose explicitly when needed:

./zurg setup --service-scope user
./zurg setup --service-scope system --service-user "$USER"

For a user service to start before the first login after a reboot, enable lingering:

loginctl show-user "$USER" -p Linger
sudo loginctl enable-linger "$USER"

Running setup as root on a server selects a system service owned by root.

4. Verify the install

./zurg doctor
curl -fsS http://127.0.0.1:9999/http/version.txt
ls /mnt/zurg/version.txt

doctor checks the config and its permissions, both downloaded tools, FUSE, the systemd unit, the HTTP endpoint and the mount reported by zurg.

A large Real-Debrid library takes time to build on its first run. The service can already be active while the first mount listing waits for that scan to finish.

version.txt answers as soon as zurg is running. A large library keeps loading after that. Its folders show up empty or as Input/output error until it is done. /ready tells you when it is.

curl -fsS http://127.0.0.1:9999/ready

Disk the mount uses

The mount caches every file it reads under ~/zurg/data/rclone-cache. It keeps the whole file after playback ends. Left alone that cache grows to 256G and stays there. It is not cleared when a video stops. The 72h age limit will not save you either. rclone counts a file as touched whenever anything reads it and a media server's nightly maintenance pass reads the whole library.

Check what it holds.

du -sh ~/zurg/data/rclone-cache

If 256G is more than the disk can spare then cap it lower in config.yml.

rclone_extra_args:
  - "--vfs-cache-max-size"
  - "50G"
  - "--vfs-cache-min-free-space"
  - "20G"

Restart zurg afterwards. To empty it by hand stop zurg first and then run this.

rm -rf ~/zurg/data/rclone-cache/vfs/* ~/zurg/data/rclone-cache/vfsMeta/*

Moving the zurg directory renames the cache and leaves the old copy behind. zurg reclaims those at the next start and logs what it freed. The details and the opt-out are in the configuration reference.

Managing zurg

Run these commands from the zurg directory:

./zurg service status
./zurg service restart
./zurg service stop
./zurg service start
./zurg service uninstall

uninstall removes only auto-start. The binary, config, data, logs and cache stay in place.

Follow logs for a user service:

journalctl --user -u zurg.service -f

For a system service:

sudo journalctl -u zurg.service -f

Updating zurg

A sponsor build replaces itself:

cd ~/zurg
./zurg update
./zurg service restart

update takes the newest nightly. It downloads it, checks the new binary reports the version it expected, and only then swaps it in by rename, so the running process is never overwritten. When the installed build is already the newest it says so and changes nothing.

update signs in to GitHub with the account you used for the install. The installer keeps the GitHub CLI in ~/zurg/bin for that. If update says it found no GitHub credential then your install is older than that change. Run the installer's update once and every zurg update after it works. The same command also updates a build too old to have zurg update. It only swaps the binary and touches nothing else.

curl -fsSL https://raw.githubusercontent.com/debridmediamanager/zurg-site/main/public/install.sh | bash -s update

A server without the GitHub CLI can set GITHUB_TOKEN instead. Use a classic token with the repo scope from the GitHub account that has zurg access.

Existing and unattended configs

Setup never replaces an existing config.yml. For unattended setup repeat --provider and supply the matching token-file or --nntp-* flags. REALDEBRID_TOKEN, TORBOX_TOKEN, ALLDEBRID_TOKEN and the NNTP_* variables work too. Run ./zurg setup --help for the full list.

See the configuration reference for every setting.