Direct downloads via Cloudflare Tunnel

Why every agent needs one

Without a tunnel, every agent download flows agent - Filestor backend - browser over the agent's WebSocket connection. With the tunnel, the backend still authorizes the download, but it answers with a redirect to a short-lived signed URL, and Cloudflare carries the bytes from the agent's machine to the browser. Backend egress per download drops to roughly one HTTP response.

Filestor requires a tunnel for every Local Drive Agent: you cannot add an agent without a tunnel hostname. R2 and S3 roots are not affected.

Prerequisites

Set up the tunnel before you add the agent in Filestor. You need:

• A Cloudflare account with a domain you control (the free tier is fine).
• cloudflared installed on the agent host.

1. Create a tunnel on the agent host

cloudflared tunnel login
cloudflared tunnel create filestor-agent

The create command prints a UUID and writes a credentials JSON file like ~/.cloudflared/<uuid>.json. Keep it.

2. Point a hostname at the tunnel

Pick a hostname under your domain, such as agent-1.example.com. It must be a DNS name: raw IP addresses, ports and paths are not accepted.

cloudflared tunnel route dns filestor-agent agent-1.example.com

3. Configure cloudflared to forward to the agent

Create ~/.cloudflared/config.yml:

tunnel: <uuid-from-step-1>
credentials-file: /home/<you>/.cloudflared/<uuid>.json

ingress:
  - hostname: agent-1.example.com
    service: http://127.0.0.1:8443
  - service: http_status:404

The agent's download server listens on 127.0.0.1:8443 by default, on loopback only. The public side is reachable solely through cloudflared.

4. Add the agent in Filestor

In Filestor: Settings → Storage → Add storage → Local Drive Agent. Enter an Agent name and the Cloudflare Tunnel hostname from step 2, then click Generate enrollment token.

Filestor creates the agent together with its tunnel and a signing key. A blank or invalid hostname is refused and no agent is created. The card that appears offers Download installer buttons. Each installer has the enrollment token, the hostname and the signing key built in.

5. Run the installer and start cloudflared

Run the installer on the agent host (see Install the Filestor agent on Linux). It enrolls the agent and runs filestor-agent configure-tunnel with your hostname and signing key before it installs the service, so there is nothing to paste. It ends by reminding you to point cloudflared at http://127.0.0.1:8443. Start the tunnel if it is not running yet:

cloudflared tunnel run filestor-agent

If you installed cloudflared as a service, restart that service instead.

Verify it works

In Enrolled agents, the agent shows a Direct downloads badge. Download a file from the agent root in Filestor. In the browser network panel, the request to /api/files/content?path=... returns 302 with a Location header at your tunnel hostname.

Agents without a tunnel

An agent added before the tunnel became required, or one whose tunnel was disabled, shows a No tunnel badge. It keeps working, but its downloads stream through the Filestor backend. To give it a tunnel:

• Do steps 1 to 3 on the agent host.
• In Enrolled agents, click Tunnel on the agent, enter the hostname, and click Enable.
• Copy the signing key. It is shown exactly once.
• On the agent host, configure the key and restart the agent:

filestor-agent configure-tunnel \
  --hostname agent-1.example.com \
  --key <paste-key-here>
systemctl --user restart filestor-agent

The key is stored in ~/.config/filestor-agent/config.json.

Rotate the key or change the hostname

Open Tunnel on the agent. Rotate key issues a new signing key for the same hostname.

To change the hostname, route the new one to the tunnel first:

• Point it at the tunnel: cloudflared tunnel route dns filestor-agent agent-2.example.com.
• Change the hostname of the ingress rule in ~/.cloudflared/config.yml to the new name and restart cloudflared.
• In the Tunnel dialog, edit the hostname and click Update, which also issues a new key.
• Run filestor-agent configure-tunnel with the new hostname and key on the agent host and restart the agent.

Emergency fallback: disable the tunnel

Disable… in the Tunnel dialog is for emergencies only, for example when the tunnel is down or its hostname is no longer under your control. It asks you to confirm first. Once disabled:

• Downloads from the agent stream through the Filestor backend again, so their bandwidth goes back through the backend.
• The agent shows No tunnel until you enable a tunnel again, which issues a new key.
• The signing key is deleted from Filestor, but not from the agent host. If you suspect the key leaked, configure a new key on the host as well, because the agent checks signatures with the key in its own config.

How auth works

• Filestor authorizes the caller and checks root/path ACLs at /api/files/content.
• It mints an HMAC-SHA256 signed URL using the per-agent signing key.
• The signed token carries the authorized root, file path, expiry, and agent ID.
• Cloudflared forwards the request to the agent unchanged.
• The agent verifies the signature and expiry, then confines the file to the signed root within its configured allowed roots.
• Range requests work natively for resumable downloads and video seeking.

Troubleshooting

• Generate enrollment token says the hostname is invalid. Enter only the DNS name, such as agent-1.example.com, without a port or path.
• Cloudflare error page. Cloudflared is not running or does not ingress to 127.0.0.1:8443.
• 401 bad signature. The agent has a different key than Filestor. Rotate the key in the Tunnel dialog and configure it on the agent host.
• 401 token expired. Reload the file viewer and try again.
• 403 path not allowed. Check the signed Filestor root and the agent allowed roots. Symlinks cannot cross into another root.
• Viewer CORS errors. Direct downloads can work without CORS, but in-app previews may need CORS headers from your tunnel hostname.