Filestor
All docs

Direct downloads via Cloudflare Tunnel

Send agent file downloads through Cloudflare Tunnel instead of proxying bytes through the Filestor backend.

Why it is worth doing

Every agent download normally flows agent - Filestor backend - browser over the WebSocket connection. With tunnel handoff, the backend emits a redirect to a short-lived signed URL and Cloudflare ferries the bytes. Backend egress per download drops to roughly one HTTP response.

This is opt-in per agent. Local, R2, and S3 roots are not affected.

Prerequisites

  • A Cloudflare account with a domain you control.
  • cloudflared installed on the agent host.
  • The agent is already enrolled and shows up in Storage - Agent.

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.

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 HTTP server defaults to 127.0.0.1:8443. The public side is reachable solely through cloudflared.

4. Enable the tunnel in Filestor

In Filestor: Storage - Agent. Find your agent, click Tunnel, enter your hostname, and click Enable.

Important: A signing key is generated and shown exactly once. Copy it before closing the dialog.

5. Paste the signing key into the agent

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

This persists the key in ~/.config/filestor-agent/config.json. Restart the agent and cloudflared:

systemctl --user restart filestor-agent
cloudflared tunnel run filestor-agent

Verify it works

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.

How auth works

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

Troubleshooting

  • Cloudflare error page. Cloudflared is not running or does not ingress to 127.0.0.1:8443.
  • 401 bad signature. Rotate the key in the Tunnel dialog and paste it again.
  • 401 token expired. Reload the file viewer and try again.
  • 403 path not allowed. The file is outside the agent allowed roots.
  • Viewer CORS errors. Direct downloads can work without CORS, but in-app previews may need CORS headers from your tunnel hostname.