sudo password once so the agent can survive logout. If you skip it, the agent still works, but it stops when you log out.Before you start
Every Local Drive Agent needs a Cloudflare Tunnel, so its file downloads skip the Filestor backend. Create the tunnel, point a hostname at it, and configure cloudflared on the Linux machine first: steps 1 to 3 of Direct downloads via Cloudflare Tunnel. You need the hostname, such as agent-1.example.com, in the next step.
1. Get your install command
In Filestor: Settings → Storage → Add storage → Local Drive Agent. Enter an Agent name and the Cloudflare Tunnel hostname, then click Generate enrollment token. A card appears with Download installer buttons. Click the one for your Linux CPU:
- Linux (x86_64) for most Intel and AMD machines.
- Linux (arm64) for Raspberry Pi 4/5, ARM servers, and AWS Graviton.
You will get a small file named filestor-agent-install.sh.
2. Run it on your Linux machine
sh ~/Downloads/filestor-agent-install.sh
The script will, in order:
- Download the agent binary into
~/.local/bin/. - Verify the SHA-256 hash.
- Enroll automatically with the token baked into the script.
- Configure the Cloudflare Tunnel handoff with the hostname and signing key baked into the script.
- Install a user systemd service that auto-starts on boot and restarts on failure.
- Print logs and status commands, and remind you to point cloudflared at
http://127.0.0.1:8443.
On any modern Linux desktop or server, the agent is now running in the background and you can close the terminal. On systems without systemd, the script falls back to running the agent in the foreground.
The installer does not start cloudflared. Start the tunnel now, or restart your cloudflared service if you installed one (step 5 of the tunnel guide). Until it runs, the agent shows as online but downloads from it fail.
cloudflared tunnel run filestor-agent
3. Verify in Filestor
In Settings → Storage → Add storage → Local Drive Agent, under Enrolled agents, the agent flips from "Pending enrollment" to Online within a second, with a version badge like v1.2.3 linux/amd64 and a Direct downloads badge for its tunnel.
Click Attach as root on that row, give the root a name, and enter the path on your machine, such as /home/alice/Documents. It now shows up as a volume under Files in the sidebar, with its Online or Offline status.
Common questions
The installer uses ~/Documents by default. How do I change that?
Open the downloaded filestor-agent-install.sh in any text editor and change ALLOWED_ROOTS="$HOME/Documents" near the top to whatever paths you want. Use commas for multiple paths.
How do I check the agent is running?
systemctl --user status filestor-agent journalctl --user -u filestor-agent -f
How do I uninstall?
systemctl --user disable --now filestor-agent rm ~/.config/systemd/user/filestor-agent.service rm ~/.local/bin/filestor-agent ~/.local/bin/filestor-agent.bak rm -rf ~/.config/filestor-agent
Then remove the agent from Settings → Storage → Add storage → Local Drive Agent in Filestor.
The agent shows as Offline after I rebooted.
Most likely loginctl enable-linger was not enabled. That requires sudo, and the installer skips it if sudo is not available. Run it once:
sudo loginctl enable-linger "$USER" systemctl --user restart filestor-agent
The agent shows a "No tunnel" badge.
Its downloads stream through the Filestor backend. This happens for an agent added before the tunnel was required, or after an admin disabled its tunnel in an emergency. See Agents without a tunnel.
The status says "Pending enrollment" forever.
You generated a token but never ran the installer, or you reused an old token. Generate a new token and rerun the installer.
Advanced: manual install
If you would rather not run a generated shell script, do its steps yourself. The Show enrollment token (for advanced setups) disclosure on the card shows the enrollment token. The binary's URL and SHA-256, the server URL, and the tunnel hostname and signing key are all in the downloaded installer: open it in a text editor and copy them from there. The signing key is not shown anywhere else.
curl -fsSL -o filestor-agent <url> echo "<sha256> filestor-agent" | sha256sum -c - chmod +x filestor-agent ./filestor-agent enroll \ --server <ws-url> --token <token> --allowed-roots ~/Documents ./filestor-agent configure-tunnel \ --hostname <tunnel-hostname> --key <signing-key> ./filestor-agent run # or wire it into systemd yourself
Agent flags: --server, --token, --allowed-roots, --config, --update-interval. The config file lives at ~/.config/filestor-agent/config.json with mode 0600.