File Sharing

File Sharing

Share a local file or directory through one HTTPS tunnel.


rstream files combines a local file server and its HTTPS tunnel. Recipients browse folders and download files through an interface included in the CLI. Your device must stay connected; files are read directly from disk. WebDAV uses normal project traffic quota; optional WebRTC can transfer directly between peers.

rstream files and the WebTTY filesystem are unavailable in the restricted FIPS profile for both WebDAV and WebRTC. See the FIPS compatibility matrix.

Start a share

After installing the CLI and selecting a project:

rstream files ./exports
rstream files ./backup.tar.zst --password

Open the forwarding URL printed by the command. With no path, the CLI shares the current directory. A file path shares only that file, including a hidden file explicitly selected this way. Stop the command to close access. Automatic reconnection is enabled; add --no-retry to stop after disconnection.

The browser offers folder navigation, sorting by name, size or modified date, filtering within the current folder, individual downloads and a ZIP of the current directory. Shares are read-only by default. The browser only offers browsing and downloads, even when WebDAV writes are enabled. Shared HTML and SVG download as attachments.

Choose access

ModeCommand optionPlans and behavior
Project defaultNo auth optionInherits project policy. If public access is permitted, anyone with the URL can use the enabled file operations, including writes when --read-write is selected.
Local password--passwordAll plans. Prompts without echo; recipients enter username rstream and this password in the browser's login prompt.
rstream account--rstream-authPro and Enterprise. Uses the usual account login and project access checks.
rstream token--token-authIncludes Basic. For HTTP/WebDAV clients that send an authorized token on every request.

Account authentication is optional. Local passwords cannot be combined with project authentication. If your project requires authentication, remove the local password option and use the project policy; the CLI rejects conflicting settings. The browser does not collect tokens.

For automation, use --password-file /path/outside/share/password or pipe a password to --password-file -. Keep that file outside the shared directory. --username changes the default username. Password values are not accepted as command-line arguments or printed in status output.

Select the files to expose

Directory shares omit dotfiles and dot-directories by default. Add --include-hidden deliberately when they are needed. Exclusions apply equally to listings, direct URLs, ZIP and writes. Selecting a single file that matches an explicit exclusion is an error:

rstream files ./exports --exclude '*.log' --exclude private

--exclude is repeatable and case-insensitive. A glob without / matches names at any depth; a root-relative glob such as reports/*.csv targets that path. Matching a directory excludes its descendants. *, ? and character classes follow Go glob rules; ** is not a recursive glob. Files outside the root, including through symlinks, cannot be read or written. In-root symlinks are supported.

Choose the transfer backend

WebDAV is the default. Add --backend webrtc for read-only peer transfers using your rstream project's STUN/TURN servers:

rstream files ./exports --backend webrtc

The browser keeps the same folder navigation and download controls. Browsers with a disk-save API choose a destination before transferring and stream without buffering the entire file in memory; progress and Cancel appear during the download. Other browsers and native link actions use HTTP attachment downloads. That compatibility path uses normal tunnel traffic.

WebRTC transfers directly between your device and the recipient when the network permits it; otherwise, rstream TURN relays the transfer. Direct file transfers bypass the tunnel. Relayed traffic uses the project's separate TURN quota.

With WebSocket terminal transport and terminal E2E disabled, enable the same transfer mode using rstream webtty server --fs-root ./exports --fs-backend webrtc. CLI clients, local MCP tools and SDKs detect the selected backend automatically. WebRTC supports listing and downloads; uploads and other write operations return a read-only error.

Enable WebDAV writes or disable the browser

These options are independent:

OptionBehavior
--read-writeEnable WebDAV uploads, replacement, directory creation, copy, move and deletion. Disabled by default; rejected with --backend webrtc.
--max-upload-size <bytes>Per-request upload limit, default 67108864 (64 MiB). Requires --read-write and a value greater than zero.
--state-dir <path>Existing persistent directory for the private upload journal; overrides RSTREAM_FILES_STATE_DIR. Available with durable WebDAV uploads.
--no-uiDisable the embedded page for either backend. / returns 404; file, archive and discovery endpoints remain available.
--output noneHide terminal output only. The embedded page remains available unless --no-ui is also selected.

For an authenticated service with WebDAV writes and no web page:

rstream files ./maintenance --name maintenance --read-write --no-ui --token-auth --max-upload-size 134217728
rstream webtty fs --url rstrm://maintenance upload ./update.bin /update.bin

The shared root must already exist. The process needs OS read/write permissions for each requested operation. Filters also protect writes through symlinks. Removing, moving or replacing a directory with hidden or excluded children is rejected; filtered subtree checks are bounded to 10,000 entries and 64 levels. A single-file share permits changes only to the selected file. Write capabilities describe enabled operations, not a guarantee that local permissions allow every target.

Uploads are available through WebDAV clients, the filesystem CLI and MCP. Browser upload controls are not yet implemented. Public access also permits writes when --read-write is enabled; choose authentication appropriate to the share.

The upload limit applies to each request body, including chunked uploads; it is not a total disk quota or a limit on server-side copies. Oversized uploads return HTTP 413. Uploads stage content beside the destination and atomically rename the complete file into place: interruptions, limits and digest failures preserve the previous file. The optional Content-Digest: sha-256=:BASE64_DIGEST: header validates content before publication; mismatches return 422. Uploads are not resumable. Partial PUT requests with Content-Range return HTTP 400. The resume capability applies only to downloads.

Regular-file ETags identify the SHA-256 of the bytes. Conditional mutations use If-Match or If-None-Match; a failed condition returns 412 without modifying the target. Services for the same export serialize admission, body reception and publication under a cancellable OS lock. Readers continue while a file is staged. This does not coordinate arbitrary local writers or separately exported overlapping roots.

Recoverable uploads and confined services

Discovery advertises content_revision, conditional_write and upload_receipts independently of write access. On supporting owners, Upload-Protocol: durable-v1 identifies durable receipts. Windows currently supports atomic uploads but not durable directory-journal synchronization; a durable request returns 501.

Clients requiring conditional, recoverable mutation use PATCH /fs/path with File-System-Action: put or delete. Durable PUT requests include a new Upload-Id, the full Upload-Length, SHA-256 Content-Digest and a revision precondition. Older owners reject this method; clients must not fall back to an unconditional PUT. After a missing response, query GET /fs/path?upload-receipt=ID before deciding what happened. A receipt lookup never repeats the write, and a lost ordinary PUT response cannot establish whether publication happened.

Receipts retain the attempt's state, recorded HTTP status, size, digest and revision. An identical request with the same ID returns its existing receipt; changed parameters return 409. An interrupted upload needs a new explicit ID. Receipts survive process restart under the same filesystem ownership discipline, have no automatic expiry, and are bounded to 4,096 per export. Full storage or journal capacity returns 507; an unavailable journal returns 503. An uncertain recovery outcome remains explicitly uncertain.

By default, the journal resides at the export root, which must permit journal writes and file locking. A service confined to a writable subtree may instead use a dedicated existing persistent directory:

mkdir -m 700 /var/lib/rstream/files-state
rstream files ./exports --read-write --token-auth --state-dir /var/lib/rstream/files-state

The CLI also accepts RSTREAM_FILES_STATE_DIR. Go embedders set fileserver.Config.StateDir or filesystem.Policy.StateDir; the library does not read that environment variable. Each export needs its own state directory, and all processes serving that export must use the same directory, including after restart. New external journals coordinate mutations there, allowing confinement that prohibits locking the export root. Upload content still stages beside its destination.

The private state subtree cannot be read or mutated through Files, including through aliases or archives. Its owner metadata binds it to the export's canonical path and filesystem identity. Startup fails for invalid or inaccessible configured state; there is no silent fallback to temporary storage.

Existing external journals retain their original root-locking behavior and receipts. New journals use owner format 2, rejected by older SDKs. Changing an existing journal's coordination requires an offline migration with all writers stopped; do not edit owner metadata, discard receipts or change the state path during a rolling upgrade. Retain the journal for as long as upload IDs can be retried.

Use a dashboard from another origin

Enable CORS explicitly for the dashboard's origin. It works with the WebDAV backend, including --no-ui:

rstream files ./exports --read-write --no-ui --token-auth \
  --cors-allow-origin https://dashboard.example

The share remains authenticated. Use an authorized delegated tunnel token on each actual request, either in Authorization: Bearer … or in the rstream.token query parameter. A valid browser preflight can succeed without a token, but it cannot read or modify files. Token expiry, resource restrictions and permissions still apply to the subsequent operation.

Files supplies WebDAV methods and request headers (including Authorization, Depth, Destination, Overwrite, conditional headers, Range and If-Range). It exposes download and resume metadata including Content-Disposition, Content-Range, Accept-Ranges, ETag, Last-Modified and Content-Length. The policy covers /_rstream/files/v1/info, /fs/, archives and errors. Write methods still require --read-write; CORS does not enable writes.

The HTTP CORS options configure additional origins and customize the policy. An explicitly supplied list replaces that list's Files defaults.

CORS is available with the WebDAV backend. It cannot be combined with --backend webrtc, which requires same-origin access.

Download with the CLI or local MCP

Give a share a name with rstream files ./exports --name exports, then download a file from another configured device:

rstream webtty fs --url rstrm://exports download /report.csv ./report.csv

The filesystem client detects WebDAV or WebRTC automatically. rstrm:// uses a private Engine connection even when the share also has a public URL. If your token can open streams but cannot read inventory, add --no-discovery and use an exact tunnel id or name. Use --fs-path for an endpoint other than /fs.

Local MCP filesystem tools accept the same target and dial privately without inventory discovery. Pass fs_path when needed. Server authentication and the share's configured write policy remain enforced. Existing CLI uploads and MCP write tools work with --read-write.

Large downloads and WebDAV

Individual downloads support HTTP Range, HEAD, ETag and Last-Modified. A client can resume an interrupted file:

curl -C - -o backup.tar.zst 'https://<share-host>/fs/backup.tar.zst'

For password access, add --user rstream to let curl prompt. When files may have changed, use an If-Range validator to avoid combining different versions. Files are live, not a snapshot: leave them stable during transfer.

The WebDAV endpoint is /fs/. Clients can use OPTIONS, PROPFIND with Depth 0 or 1, GET and HEAD. Write methods are forbidden by default. With --read-write, WebDAV also accepts PUT, MKCOL, COPY, MOVE and DELETE. URL-encode each path segment, including spaces, #, ? and % in filenames. The browser handles this automatically.

ZIP streams while it downloads, without staging the full archive. An interrupted ZIP must restart. Two ZIP streams can run simultaneously; further requests receive HTTP 429 and can retry. A directory may contain at most 10,000 raw entries for listing; share a smaller directory if HTTP 507 is returned. Archives are limited to 100,000 entries and 64 directory levels, and reject symlink cycles. They support ZIP64 for large files and use store mode rather than compression. The browser displays 100 entries per page.

Tunnel options and automation

Use --name, --host and repeatable --label for naming, a stable domain and metadata. Global context, region, transport and logging options apply normally, including mTLS with an external signer. Authentication, hostname, labels, write mode and UI selection are retained across reconnections. The shared YAML context supplies connection and authentication settings; this imperative command does not add a declarative files resource or Docker labels. --retry-interval sets the reconnection interval in milliseconds.

-o json emits the tunnel status and forwarding URL plus files metadata: contract version, shared name, kind, backend, access and capabilities. The same metadata is available at /_rstream/files/v1/info. Backend is webdav or webrtc; read, list and resume are supported, write reflects whether WebDAV writes are enabled, e2ee is false, and archive is available only for directory shares. Writable shares also advertise max_upload_size_bytes. Discovery remains available with --no-ui; the contract version remains 1.

A file share runs independently of WebTTY and does not require registering a WebTTY server. The WebTTY filesystem sidecar also works on lightweight and registered persistent servers when the terminal uses WebSocket and E2E is disabled. WebDAV and WebRTC backends use the advertised filesystem endpoint; WebTransport terminals currently have no filesystem sidecar.

Encryption and the hosted file-sharing tool

With WebDAV, HTTPS encrypts traffic between the recipient and rstream, and the agent tunnel encrypts traffic between rstream and your device. WebRTC encrypts the peer connection, including when TURN relays the transfer. HTTP compatibility downloads use the WebDAV transport path.

rstream files does not encrypt files with a separate, recipient-held key. The hosted file-sharing tool encrypts files before upload and includes the decryption key in the download link. Use rstream files to keep files on your connected machine and let recipients browse or resume downloads; use the hosted tool for a temporary encrypted upload.