Handrive Headless Mode: Always-On File Sharing for Post-Production Studios

The main objection to P2P file transfer is the "both parties online" requirement. If you're in LA and your editor is in London, coordinating schedules for every transfer is impractical.

Headless mode solves this. Run Handrive on a server or NAS at your studio, and it becomes an always-on endpoint. Teams upload to the server whenever they're ready; others download whenever they're ready. No coordination required.

What You Get

• 24/7 availability: Server is always online, shares always accessible
• Cloud-like convenience: Async workflows without cloud costs or privacy concerns
• Central storage: One location for all project files
• REST API: Integrate with your existing tools and scripts
• MCP server: AI agents can manage files 24/7
• Still free: No per-GB fees, even running on a server

Hardware Requirements

Headless Handrive is lightweight. You can run it on:

• Synology NAS: Most models support Docker or direct binary
• QNAP NAS: Similar Docker/binary support
• Linux server: Any x64 or ARM64 Linux box
• Raspberry Pi 4+: ARM64 support, minimal power consumption
• Cloud VM: AWS, GCP, Azure (though this somewhat defeats the privacy purpose)

Minimum specs:

• 1 CPU core
• 512MB RAM
• Linux x64 or ARM64
• Network connectivity

Setup Guide

Step 1: Download the Binary

# SSH into your server
ssh user@your-server

# Check architecture
uname -m

# Download appropriate binary
# For x86_64:
wget https://downloads.handrive.app/handrive-linux-x64

# For ARM64:
wget https://downloads.handrive.app/handrive-linux-arm64

# Make executable and move to PATH
chmod +x handrive-linux-*
sudo mv handrive-linux-* /usr/local/bin/handrive

Step 2: Authenticate

# Start the server (in one terminal or tmux)
handrive serve --port 3001

# In another terminal, authenticate
handrive auth login otp studio@yourcompany.com
# Enter the OTP code sent to your email

Step 3: Set Up as a Service

Create a systemd service so Handrive starts on boot and restarts if it crashes:

# Create service file
sudo nano /etc/systemd/system/handrive.service

Add this content:

[Unit]
Description=Handrive P2P File Sharing Server
After=network.target

[Service]
Type=simple
User=handrive
Group=handrive
WorkingDirectory=/home/handrive
ExecStart=/usr/local/bin/handrive serve --port 3001
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

# Create a dedicated user (recommended)
sudo useradd -r -s /bin/false handrive
sudo mkdir -p /home/handrive
sudo chown handrive:handrive /home/handrive

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable handrive
sudo systemctl start handrive

# Check status
sudo systemctl status handrive

Step 4: Create Shares

Now create shares that team members can access. You can do this via:

• REST API: curl http://localhost:3001/api/shares ...
• MCP + Claude: "Create a share called Project Alpha"
• Desktop app: Connect to the headless server from your laptop

Architecture Patterns

Pattern 1: Central Studio Server

Most common setup. Single server at the studio office that everyone connects to.

┌─────────────┐
│  DIT on set │────┐
└─────────────┘    │    ┌────────────────────┐
                   ├───▶│  Studio Server     │
┌─────────────┐    │    │  (Headless Mode)   │
│   Editor    │────┤    │                    │
└─────────────┘    │    │  - 24/7 online     │
                   │    │  - Central storage │
┌─────────────┐    │    │  - REST API        │
│  Colorist   │────┘    │  - MCP for AI      │
└─────────────┘         └────────────────────┘
              

Pattern 2: Multi-Location

Studios with offices in multiple cities can run headless servers at each location.

┌───────────────┐         ┌───────────────┐
│  LA Office    │◀───────▶│  NYC Office   │
│  Server       │         │  Server       │
└───────────────┘         └───────────────┘
       ▲                         ▲
       │                         │
  Local team               Local team
              

Pattern 3: Vendor Handoff Point

Use a headless server specifically for external vendor communication.

┌─────────────┐
│ Internal    │
│ Systems     │
└──────┬──────┘
       │
       ▼
┌─────────────────────┐
│  Vendor Gateway     │
│  (Headless Server)  │
│                     │
│  - VFX handoffs     │
│  - Sound handoffs   │
│  - Client delivery  │
└──────┬──────────────┘
       │
       ▼
┌─────────────┐
│ External    │
│ Vendors     │
└─────────────┘
              

AI Automation on Headless Servers

Headless servers expose the full MCP API, so AI agents can manage them 24/7:

• Monitor incoming folders for new uploads
• Automatically organize files by project/date
• Add/remove members based on project schedules
• Generate reports and manifests
• Trigger notifications when files arrive

Configure Claude Desktop to connect to your headless server's MCP endpoint and you have AI-powered file management running round the clock.

Security Considerations

• Firewall: The headless server uses NAT traversal, so you typically don't need to open ports. But review your firewall rules.
• Authentication: Each user must authenticate. The server stores credentials locally.
• Physical security: The server stores file data. Ensure physical access is controlled.
• Backups: Implement standard backup procedures for the server's storage.

Troubleshooting

Server won't start

# Check logs
sudo journalctl -u handrive -f

# Common issues:
# - Port already in use: change --port value
# - Permission denied: check user/group settings
# - Binary not found: verify PATH

Can't connect from outside

• Verify server firewall allows outbound connections
• Check that NAT traversal isn't blocked by network policy
• Try temporarily disabling firewall to isolate issue

Authentication issues

# Check auth status
handrive auth status

# Re-authenticate if needed
handrive auth logout
handrive auth login otp your@email.com