Clustering

Handrive is cluster-native. Login on unlimited devices with the same email, and run multiple instances per machine to maximize hardware utilization. Everything syncs automatically.

Multi-Device

Use the same email to login on as many devices as you want, anywhere in the world:

  • Laptop at home
  • Desktop at work
  • Mac Mini as always-on server
  • Raspberry Pi as NAS
  • Cloud VM for remote access

All devices automatically sync:

  • Shares and folder structure
  • Contacts
  • Share memberships
  • File metadata
# Login on any device with the same email
hand auth login otp alice@example.com

# All your shares appear automatically

Multi-Instance

Run multiple Handrive instances on a single machine to maximize CPU, memory, and I/O utilization:

# REST API on multiple ports
hand serve --port 4263
hand serve --port 4264
hand serve --port 4265

# Or mix REST API with MCP
hand serve --port 4263  # For HTTP clients
hand mcp                 # For AI agents

All instances share state and coordinate automatically:

  • Changes in one instance appear instantly in others
  • Requests are distributed across instances
  • No configuration needed

Multi-Instance as Services

For a single instance, use hand service install — no manual setup required.

For multi-instance deployments, create custom service files since the service command only manages one instance:

Linux (systemd)

Create a template service at /etc/systemd/system/handrive@.service:

[Unit]
Description=Handrive Instance %i
After=network-online.target

[Service]
Type=simple
User=handrive
ExecStart=/usr/local/bin/hand serve --port %i
Restart=always

[Install]
WantedBy=multi-user.target
sudo systemctl enable handrive@4263 handrive@4264 handrive@4265
sudo systemctl start handrive@4263 handrive@4264 handrive@4265

macOS (launchd)

Create plist files for each instance at ~/Library/LaunchAgents/ai.handrive.instance-PORT.plist:

# Load multiple instances
launchctl load ~/Library/LaunchAgents/ai.handrive.instance-4263.plist
launchctl load ~/Library/LaunchAgents/ai.handrive.instance-4264.plist
launchctl load ~/Library/LaunchAgents/ai.handrive.instance-4265.plist

Windows (Task Scheduler)

Create scheduled tasks for each instance:

# Create tasks for each port
schtasks /create /tn "Handrive-4263" /tr "hand serve --port 4263" /sc onlogon
schtasks /create /tn "Handrive-4264" /tr "hand serve --port 4264" /sc onlogon
schtasks /create /tn "Handrive-4265" /tr "hand serve --port 4265" /sc onlogon

# Start them
schtasks /run /tn "Handrive-4263"
schtasks /run /tn "Handrive-4264"
schtasks /run /tn "Handrive-4265"

Use Cases

Personal Cloud

Login on all your personal devices. Access your files from anywhere without relying on third-party cloud storage.

Team Collaboration

Each team member logs in with their email. Shared folders sync across all members' devices automatically.

High-Throughput Server

Run multiple instances on a powerful server to handle many concurrent transfers and API requests.

Hybrid Desktop + Headless

Use the desktop app for visual file management while a headless instance serves AI agents via REST API or MCP.

See Also