v0.1.0 Early Access

ShelDrive Documentation

Mount Shelby Protocol decentralised storage as a native drive on your Mac. Copy files in — they're pinned to the network. Read files — they're retrieved on demand.

Installation

Prerequisites

ShelDrive requires FUSE-T to create a virtual filesystem on macOS. FUSE-T is a userspace implementation — no kernel extensions, no reduced security, no restart needed.

$ brew install --cask fuse-t

You also need Node.js 20+ installed (for the Shelby SDK sidecar).

$ brew install node

Install ShelDrive

Download the latest .dmg from the releases page, open it, and drag ShelDrive to your Applications folder.

Or build from source:

      $ git clone https://github.com/TaffForest/ShelDrive.git

      $ cd ShelDrive

      $ npm install

      $ cd sidecar && npm install && npm run build && cd ..

      $ npx tauri build

Configuration

ShelDrive reads its configuration from ~/.sheldrive/config.toml. Create it on first use:

      $ mkdir -p ~/.sheldrive

      $ cat > ~/.sheldrive/config.toml << 'EOF'

      [shelby]

      network = "TESTNET"

      api_key = "your-api-key"

      rpc_url = "https://api.testnet.shelby.xyz/shelby"

      private_key = "your-ed25519-private-key-hex"

      EOF

Key	Description	Default
`network`	Shelby network to use	`TESTNET`
`api_key`	Your Shelby API key	—
`rpc_url`	Shelby RPC endpoint	Auto-detected
`private_key`	Ed25519 private key (hex)	—

Mock mode

Without a private_key, ShelDrive runs in mock mode — files are stored locally but not pinned to the Shelby network. This is useful for testing.

First Mount

Launch ShelDrive from Applications
The app appears in your menu bar / system tray
Click the tray icon to open the panel
Click Mount
A Finder window opens at ~/ShelDrive
Drag files in — they're pinned to Shelby

File Operations

Once mounted, ~/ShelDrive works like any folder. All standard operations are supported:

      # Write a file

      $ echo "hello" > ~/ShelDrive/test.txt

      # Read it back

      $ cat ~/ShelDrive/test.txt

      # Copy a file in

      $ cp ~/Documents/report.pdf ~/ShelDrive/

      # Create directories

      $ mkdir ~/ShelDrive/photos

      # Delete a file (unpins from Shelby)

      $ rm ~/ShelDrive/test.txt

      # List directory

      $ ls ~/ShelDrive/

You can also drag and drop files in Finder — it works the same way.

Finder Integration

When you click Mount, a Finder window opens automatically showing the ShelDrive folder. To pin it to your sidebar permanently:

Open the ShelDrive folder in Finder
Drag it from the window into the Favorites section of the sidebar

Offline Mode

ShelDrive works without internet. Files you write are stored in a local disk cache at ~/.sheldrive/cache/ and queued for upload when connectivity returns.

Writes: Always succeed — content goes to disk staging immediately
Reads: Served from local cache if available, fetched from Shelby on cache miss
Cache size: 512 MB LRU cache, oldest files evicted when full

Sidecar auto-restart

If the Shelby SDK sidecar crashes, ShelDrive automatically restarts it up to 3 times. Your files remain safe in the local cache during any downtime.

Content Filtering

ShelDrive includes built-in safety features to prevent dangerous or illegal content from being pinned to the decentralised network. All scanning runs locally on your device — no file content is sent to external services.

Blocked File Types

The following file types are blocked at creation time and cannot be written to the drive:

      .exe   .bat   .cmd   .scr

      .dll   .com   .msi   .ps1

      .vbs   .wsf   .cpl   .hta

      .inf   .reg   .pif   .lnk

      .sys   .sct   .shb   .wsc

Attempting to create these files returns "Operation not permitted".

Size Limits

Limit	Value
Max file size	`2 GB`
Virtual drive capacity	`1 TB` (reported to OS)
Local cache	`512 MB` LRU

Image Scanning

Image files (.jpg, .png, .gif, .webp, .bmp) are validated before pinning to the Shelby network:

File header validation — rejects files that claim to be images but aren't
NSFW content detection — on-device ML model (coming soon)

How It Works

Your app (Finder, Terminal, etc.)

    ↓

macOS kernel → FUSE-T (userspace filesystem)

    ↓

ShelDriveFS (Rust) — handles read/write/delete

    ├ SQLite index — maps paths to Shelby CIDs

    ├ Disk staging — buffers writes to disk

    └ Disk cache — LRU cache for fast reads

    ↓

ShelbyBridge (JSON-RPC over stdio)

    ↓

Node.js sidecar → @shelby-protocol/sdk

    ↓

Shelby Network (decentralised hot storage)

Write flow

File data written to disk staging at ~/.sheldrive/staging/
On file close, content is base64-encoded and sent to the sidecar
Sidecar calls ShelbyClient.upload() to pin to the network
Returned CID stored in SQLite, content moved to disk cache

Read flow

Check disk staging (file being actively written)
Check disk cache at ~/.sheldrive/cache/
Fetch from Shelby network via sidecar, cache locally

Data Locations

Path	Contents
`~/ShelDrive/`	FUSE mount point (virtual drive)
`~/.sheldrive/config.toml`	Configuration
`~/.sheldrive/index.db`	SQLite path → CID index
`~/.sheldrive/cache/`	LRU file content cache
`~/.sheldrive/staging/`	Active write buffers

Tech Stack

Layer	Technology
App shell	Tauri v2 (Rust + WebView)
Filesystem	FUSE via `fuser` crate + FUSE-T
Storage SDK	`@shelby-protocol/sdk`
Local index	SQLite via `rusqlite`
Frontend	React + TypeScript
IPC	JSON-RPC 2.0 over stdin/stdout

Common Issues

"File exists" error on mount

A stale FUSE mount or leftover files at the mount point. ShelDrive auto-cleans on mount, but if it persists:

      $ sudo umount -f ~/ShelDrive

      $ rm -rf ~/ShelDrive

"No space left on device"

The virtual drive needs the statfs response from FUSE. If you see this, update to the latest version which reports 1TB virtual capacity.

Sidecar shows "Mock mode"

The Shelby SDK couldn't connect. Check your ~/.sheldrive/config.toml has valid api_key and private_key values. Without a private key, ShelDrive runs in mock mode where files are stored locally only.

Files not appearing in Finder

Check the drive is actually mounted:

      $ mount | grep ShelDrive

      $ ls ~/ShelDrive/

App shows white screen

This happens when launching the dev build from the dock after the Vite server has stopped. Use the production build from /Applications/ShelDrive.app instead.