RSAF: putting rclone remotes behind Android's document picker

RSAF is a document provider, not a file manager

RSAF is an Android document provider for rclone, which is the key to understanding how it fits into Android. It does not present a file manager interface of its own. Instead it registers itself with the Storage Access Framework, so any app that can pick a document can browse the remote files rclone is configured to reach.

The documentation makes the point explicitly: RSAF is not itself a file manager, but any file manager supporting SAF, including the one built into Android under Settings, Storage, Documents, can make use of it. The repository ships light and dark mode screenshots of the system picker showing the provider, which is how the feature presents itself in practice.

The alternative users might expect is to install rclone itself on the device and use a terminal, or to run a local file server and point a file manager at it. RSAF takes a different route, and the difference in approach is that it does not require the user to think about remotes at all. Once configured, the remotes simply show up next to internal storage in any document picker, which means apps that only know how to read a file descriptor never learn that the file is on someone else's server.

The language is Kotlin for the Android side, and the repository contains an `app/` directory along with an `rcbridge/` directory, plus an `external/` directory and a `.gitmodules` file, so some components come from elsewhere. The licence is GPL-3.0.

The permission list is one line long

The feature list claims no required permissions besides network access, and the permissions section backs that up. The `INTERNET` permission is the main one, used only to let rclone reach the configured remotes. The documentation adds that RSAF does not and will never have ads or telemetry.

Two more permissions appear with conditions attached. On Android 17 and later, `ACCESS_LOCAL_NETWORK` is needed to reach hosts on the local network, and it is explicitly not required for hosts on the internet. The `RECEIVE_BOOT_COMPLETED` permission lets RSAF resume pending uploads that were interrupted by a crash or a reboot.

Two more are advisory rather than required. Allowing notifications and disabling battery optimizations are optional, but the documentation calls them strongly recommended, and gives the reason: they are needed for RSAF to run reliably in the background after a client app closes a file, which is when file uploads actually begin. That timing detail explains the whole asynchronous design, and it is the kind of thing that only shows up after a first session of files appearing to save instantly and arriving later.

On Android 11 and later, RSAF can optionally request `MANAGE_EXTERNAL_STORAGE`, the All files permission, which lets rclone reach files in /sdcard. The documentation gives a concrete reason it might matter, since it allows a `crypt` remote to transparently encrypt and decrypt files in a local directory.

The app supports Android 9 and newer.

Verification is a two step check against a published digest

Because RSAF handles remote storage credentials, the project documents how to verify the APK you downloaded. The first step prints the digests of the APK signing certificate with `apksigner`:

apksigner verify --print-certs RSAF-<version>-<arch>-release.apk

The second step is to compare the SHA-256 digest of that certificate against the one published in the documentation:

b2506499bea1c5a6e658f07be6773fe486999dc124204c6522af7407503ac9f9

There is a fallback for machines without `apksigner` installed. The APK files can be verified against external `.apk.sig` SSH signatures, using the steps in the VERIFY_SSH_SIGNATURES.md file in the project's other repository.

Installation is otherwise unremarkable. The usage section has three steps: download the latest version from the releases page, import an existing rclone configuration or configure one from scratch inside the app, and then the configured remotes are available through the Storage Access Framework. There is no separate server, no root and no account of your own, since the authentication belongs to the rclone backend.

Release history shows the project is moving quickly, with version 4.14 on 2026-10-10, 4.13 on 2026-10-09 and 4.12 on 2026-09-05, and the last push was on 2026-10-15. A `CHANGELOG.md`, a `RELEASE.md` and an `UPDATES.md` sit at the top of the repository, so the change history is there to read.

Async close and missing ftruncate are the real limits

The limitations section is the most useful part of the documentation, because the Storage Access Framework imposes limits that no amount of care in the app can remove.

Fancier file descriptor system calls are not supported. The reason is given as an Android API limitation, referencing `ProxyFileDescriptorCallback`: only the normal `lseek()`, `read()`, `pread()`, `write()`, `pwrite()` and `fsync()` calls work. Notably `ftruncate()` is not supported. So a client that truncates a file to a length is out of luck, and an app that does so may misbehave in ways RSAF cannot intercept.

The `close()` behaviour is the second sharp edge, and it comes from Android's internal FUSE implementation. `close()` is asynchronous and cannot be made synchronous, so a file may not be fully uploaded when `close()` returns. The documentation names the scenario this breaks, writing to a temporary file and then renaming it afterwards. RSAF works around it by making file renaming, copying and moving wait until the relevant background uploads are complete, and the wording is careful that this cannot be made completely foolproof.

Random writes are the third. RSAF permits them, but rclone does not handle them efficiently and will download and reupload the whole file. The documentation compares the behaviour to `rclone mount --vfs-cache-mode writes`, which is a useful way to predict the cost.

A fourth limitation is quieter: client applications may not be able to detect errors. The document provider API has no way to report errors for certain operations such as listing a directory, so some apps treat an error, which arrives as a null response, and an empty directory as the same thing.

The encrypted config is what breaks root-based backup

RSAF stores its rclone configuration encrypted, and the reason it does so is the source of a sharp edge in the documentation.

The internal config file is encrypted with a password that is itself wrapped by a hardware key. Because hardware keys cannot be backed up even with root access, restoring RSAF's app data using a root-based backup tool leaves the config file undecryptable. The application's behaviour in that case is a crash rather than a degraded mode. The documentation points at the built-in config import and export feature as the correct path instead.

There is an optional alternative. If the `Allow Android backups` option is enabled, Android can back up RSAF's app data through Google Drive on official Android builds, or Seedvault on some custom Android systems. The option is disabled by default, and the reasoning is that RSAF cannot verify that the conditions are really true. The two conditions are that the backup mechanism is end-to-end encrypted, and that the app data is sent directly to a new device as part of device setup without first being uploaded to the cloud. The documentation notes that some older OEM Android builds have backup systems that lie about end-to-end encryption.

The reason the backup mechanism has to be trustworthy is stated plainly: the rclone configuration holds the credentials for your remote storage, and RSAF backs that configuration up in plain text.

The configuration interface itself is not translated, and the reason is a design choice rather than an oversight. To keep the code simple, the configuration system presents interactive questions in the same style as the `rclone config` command, and since rclone has no internationalization support, those questions are always in English.

Filename counters reduce collisions without removing them

File operation semantics in the Storage Access Framework have one behaviour worth knowing before you write a client app against RSAF.

When creating, renaming, copying or moving a file or directory, RSAF adds a counter to the filename to try to avoid a conflict, producing something like `file(1).txt` if the target path already exists. The documentation notes that this matches the Storage Access Framework behaviour for local files, and that RSAF extends the same treatment to copying and moving rather than only creation and renaming.

The honest caveat follows immediately. The feature cannot be implemented in a completely foolproof way, and if two client applications create files with the same name at the same time, they can still clobber each other's data even with the counter in place. A file manager that reports a name and then acts on it later has a race, and the counter narrows the window without closing it.

The rest of the feature list is about coverage rather than semantics. All rclone remote backends are supported, including those that require OAuth 2.0. Server-side copy and move are supported for backends that implement the feature, which is the difference between a copy that streams through the phone and one that asks the server to do it. Client applications that request a file descriptor are supported, and so are applications that open entire directories using `ACTION_OPEN_DOCUMENT_TREE`.

There is one more feature aimed at a specific class of app. RSAF can pretend to be local storage for apps that block remote SAF roots, which is a workaround for apps that refuse to open a document from a provider they do not recognise as local.

Editorial conclusion

RSAF fits Android users who store files in rclone backends and want those remotes to appear in the system document picker, since it asks for network access and nothing more, and it handles OAuth 2.0 backends and random reads. Do not adopt it where a build pipeline assumes POSIX semantics for a remote file, because `ftruncate()` is unsupported, `close()` is asynchronous, and a random write downloads and reuploads the whole file. Before you rely on it, verify the APK signature with `apksigner verify --print-certs` against the documented SHA-256 digest, and if you move the app to a new device, use the built-in config import and export rather than a root-level backup, which will leave the encrypted config undecryptable.

Frequently asked questions

Official sources

1. chenxiaolong/RSAF on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases