# Remote library: web accounts, local mount The remote library is read-only, optional and **disabled by default**. It requires an active paid plan (including PRO+ and paid lifetime access). Free accounts, free trials and expired plans cannot use it. The web profile's Agents section shows a purchase CTA or setup instructions for the current plan. Startup checks the web entitlement before opening the listener or cache. While running, the CLI rechecks every 30 seconds and closes the service if verification fails (including network loss; a request has a ten-second timeout). Provider accounts are configured once on the Unarr website. Their API keys stay encrypted in the existing web database; the CLI never receives debrid API keys. There is no separate local provider configuration or encryption key file. ## Setup 1. Connect your Real-Debrid, AllDebrid, TorBox or Torrin account in the existing Unarr web settings. Configure Usenet there too if you want direct NZB access. 2. Run `unarr init` to configure the normal agent, including its download directory and registered device identity. Then run `unarr mount`. On first use, enable the optional feature. Missing/expired device authentication opens the existing browser sign-in flow; a valid session is reused. 3. unarr checks paid access, reuses compatible dependencies and downloads a pinned, SHA-256-verified official rclone into its private tools directory. Before installing a missing FUSE/macFUSE/WinFsp driver, it explains why it is needed and any system password, approval or restart, then asks permission. 4. The default folder is `~/unarr-media` on Linux/macOS; Windows chooses a free drive letter. A custom destination is `unarr mount /path/to/remote-media`. The command saves the enabled intention after validation and dependency setup, then requests installation or restart of the normal agent service. Its success message confirms configuration and that activation was requested; check the folder and agent logs to confirm actual mount readiness. The agent owns the mount after the terminal closes and retries after login/reboot. Run `unarr umount` (or `unarr unmount`) to disable it. `unarr config mount` remains available for advanced local settings. On Windows, use an unused drive letter (`unarr mount X:`) or a nonexistent directory below an existing parent. Linux/macOS create a missing directory and reject nonempty destinations. Bare ASCII drives `A:` through `Z:` are accepted; occupied drives and drive-relative paths such as `X:media` are rejected. Existing files are never replaced. Windows mounts require WinFsp 1.9 or newer. The verified installer provides 2.1; existing installations below 1.9 are unsupported and must be updated before mounting. The Windows mount uses protected owner read/execute permissions to deny creation, writes, renames and deletion while allowing media reads and directory listing. This permission behavior was validated with WinFsp 2.1; older drivers were not tested. The agent starts a loopback WebDAV service and rclone. They share the agent's lifecycle and are retried after transient failure. Stopping the whole agent also stops the mount; starting it again restores an enabled mount. Persistent `mount` and `umount` use the one default agent service and its default config: `~/.config/unarr/config.toml` on Linux, `~/Library/Application Support/unarr/config.toml` on macOS, and `%APPDATA%/unarr/config.toml` on Windows. A different `--config`, `UNARR_CONFIG_DIR`, shell-only `UNARR_API_KEY`, `UNARR_API_URL`, `UNARR_DOWNLOAD_DIR`, `UNARR_COUNTRY`, `UNARR_TELEMETRY`, or Linux `XDG_CONFIG_HOME`/`XDG_DATA_HOME` override is refused before authentication, configuration writes or service operations. Save these settings in the default file instead. `mount serve --config /path/to/config.toml` remains available for an independently managed process. `umount` preserves stopped and parked service intent; it requests a restart only for a running installed service. Saving a disabled mount setting does not apply it to an existing mount session. Run `unarr umount` to unmount that session even when the saved setting is already off. Each running mount uses an immutable snapshot of the agent's current key and identity. A minted key, revocation or replacement sign-in cancels and joins the old DAV, catalog, readers and rclone before starting another session. The agent also checks saved identity changes every five seconds while mounting. Removing the identity stops mounting until a new identity is available. Daemon exits cancel and wait for mount cleanup with a fifteen-second bound; rclone is given five seconds to exit before being terminated. Dependency preparation never runs while disabled. The normal daemon may validate or reuse the private rclone binary, but noninteractive sessions cannot approve system installations or enable the feature. On supported Linux distributions unarr uses apt/dnf/yum/pacman/zypper/apk and sudo/doas if needed. macOS uses the verified official macFUSE installer; Windows installs the default WinFsp components with a progress indicator after explaining the installation and requesting consent. Native UAC prompts remain, and automatic restarts are disabled. macOS security approval/recovery changes are never automated. Unsupported distributions and containers without host FUSE access get actionable instructions. `mount serve` needs neither rclone nor a filesystem driver. Older rclone installations are reused only when they support all required mount options. Incompatible versions get a private verified replacement; the user's existing executable is preserved. Inactive macFUSE requires explained activation and any native security approval. On Arch, installing missing FUSE also performs a full system upgrade to avoid a partial upgrade; this is explicitly disclosed before consent. See [the test matrix](REMOTE_MOUNT_TEST_MATRIX.md) for native results and remaining platform limitations. The complete local settings are: ```toml [mount] enabled = false # set true explicitly, or use unarr config mount directory = "/home/me/unarr-media" # persisted by unarr mount listen = "127.0.0.1:11820" # loopback only refresh_interval = "1m" # minimum 10s # cache_dir = "/absolute/path/to/private-metadata" # nzb_dir = "/absolute/path/to/nzbs" ``` No provider names, tokens, NNTP host/password or duplicate WebDAV password are stored in this section. Device authentication continues to use Unarr's existing login mechanism. The local WebDAV credentials are derived in memory from that login using the existing credential derivation. Local paths and listener changes require restarting the agent; web account changes are discovered on refresh. Example tree: ```text remote-media/ debrid/real-debrid/Release [id]/video.mkv debrid/alldebrid/Season [id]/episode.mkv debrid/torbox/Release [id]/video.mkv debrid/torrin/Release [id]/video.mkv usenet/NZB filename [stable-id]/video.mkv ``` ## Web/CLI contract The matching web backend must be deployed before this CLI feature can work. The backend includes the paid-access gate and the web profile configuration. Deploy that backend before publishing the CLI release. All mount endpoints reuse the existing agent authentication and derive the user from the authenticated key, never a caller-supplied user ID: - `GET /api/internal/agent/mount/access`: validates the current paid plan at startup and every 30 seconds while mounted. - `GET /api/internal/agent/mount/accounts`: connected supported accounts and opaque account revisions, without raw or encrypted provider credentials. - `GET /api/internal/agent/mount/library`: paginated metadata and signed file references. The backend reuses the existing debrid clients, transport and concurrency controls. - `POST /api/internal/agent/mount/resolve`: validates the reference, its owner and current account revision, rechecks the exact file and resolves its URL. The media bytes then flow directly from the CDN to the CLI. References cannot be moved between users or replayed against a replaced account. Removing an account removes its entries after a successful refresh. Previously resolved CDN URLs and active readers can remain usable until upstream expiry; the mount does not claim immediate revocation of those already-issued URLs. For Usenet NZBs, the CLI uses `/api/internal/agent/mount/usenet-credentials`, which adds the paid-plan gate to the existing Usenet credential resolver. NNTP needs the credentials on the device to connect directly: they are fetched lazily, retained only in memory, refreshed after five minutes on subsequent article access, and never written to the mount configuration or catalog. This endpoint retains the existing web-side Usenet entitlement checks. The web action **Add to local Usenet folder** dispatches only the selected NZB manifest to a compatible online agent (reserved future CLI floor: 1.17.0), which stores it in the managed `mount-nzbs` inbox beside `config.toml`. If there is no agent, the web shows the install CTA; an older agent gets the update CTA. Copying a complete `.nzb` file into the same inbox manually is also supported. Remote mounting is not released; CLI 1.17.0 is reserved and unpublished. The published 1.16.0/1.16.1 agents do not support this feature. ## Continuity and limits Metadata snapshots and a private local database keep listings available during outages and after restart. Failed refreshes retain known entries and can publish safe partial progress. Account removals apply after a successful complete scan. Mount setup, paid-access checks and source requests use the existing configured API mirrors for transient failures. A paid-access denial is not retried through another mirror. Missing files in a direct NZB do not hide healthy siblings; partial manifests are retried on later refreshes while retaining known entries. The cache defaults to `remote-library/` beside the selected config, honoring `--config`. It contains metadata and signed references, not media or API keys. Access probes give each mirror attempt three seconds, leaving time for a healthy mirror inside the ten-second access watchdog. Metadata and URL resolution use a finite thirty-second budget per mirror attempt to cover cold provider pacing and queued resolution; caller cancellation can shorten it. 403/410 denials are terminal. Library pages keep the `entries`/`next` envelope and `path`/`key`/`size`/`reference` entry fields; `next` is an opaque signed cursor, including when a single release spans pages. The serialized response limit is 1048576 bytes inclusive; larger responses fail explicitly without including their body in the error. Stat, HEAD, directory listings and seek bookkeeping do not contact the CDN or NNTP provider. WebDAV listings have a generation-aware cache bounded to 16 MiB and 256 responses. Independent readers fetch byte ranges on demand, validate upstream ranges/lengths, and share lazy URL resolution and renewal. The server admits 32 concurrent GET requests. Built-in rclone uses a 4 MiB buffer per open file, 32–128 MiB read chunks, a 15-second directory cache and no full-file disk cache. Usenet reuses the existing bounded article cache and 16 warm plans. TorBox enumeration includes torrents, Usenet and web downloads. Torrin uses its native cursor-paginated jobs API. Real-Debrid and AllDebrid reuse cached file metadata for unchanged releases. The backend coalesces concurrent metadata requests and limits retained serialized metadata to 16 MiB / 2,048 entries. Only the four supported **personal** provider accounts are exposed. Managed credentials that may belong to shared pools are excluded to prevent exposing other users' files. Premiumize and other adapters still need account enumeration. Unsupported compressed/encrypted archives, ambiguous multi-video RARs and zipped TorBox members are not silently presented as independently streamable files. Direct Usenet watches the nonrecursive managed NZB inbox. The website can add manifests through the agent, or you can add complete files manually by renaming them to `.nzb`. It supports direct files (including episodes/subtitles) and the existing uncompressed RAR4/RAR5 streaming paths. The original download workflow remains available for other archives. ## Service-only and containers `unarr mount serve` starts the authenticated loopback WebDAV endpoint without rclone. Use the existing derived Unarr WebDAV credentials with an independently managed rclone remote. Only one mount process may own a given catalog/listener. In containers, server and rclone must share a network namespace; host-visible FUSE additionally requires the device, permissions and mount propagation. The project's default Docker setup does not supply these automatically. This is the local-folder use case, not full Zurg feature parity: automatic torrent repair/re-add, provider writes, virtual rename and Arr download-client emulation are outside this feature. No real-provider comparison with Zurg has been demonstrated. See [performance and validation](REMOTE_MOUNT_PERFORMANCE.md). If you tried the earlier, unreleased local-provider configuration, reconnect those accounts on the web and remove `mount.providers`, `mount.usenet` and local mount credentials from TOML. Those keys are now unknown settings. `unarr config encrypt` and the experimental local key-file format were removed; do not carry its encrypted fields into the standard login configuration.