Headless Server Guide

Run Handrive as a headless server on Linux, macOS, or Windows for always-on file sharing without a graphical interface.

Overview

What is Headless Mode?

Headless mode runs Handrive without the graphical user interface using the handrive serve command. It provides:

• HTTP API Server: REST API access for automation and integration
• MCP Server: Model Context Protocol support for AI assistants (via handrive mcp)
• Always-On Access: Files available 24/7 from a server

Use Cases

• Home Server / NAS: Always-available sync point for all devices
• Cloud Server: Reliable sync between distributed devices
• Automation: MCP server for AI-powered file management

Prerequisites

Supported Platforms

System Requirements

Linux Setup

Download and Install

Linux (x64):

# Download
curl -L https://handrive.app/download/linux-x64 -o handrive

# Make executable
chmod +x handrive

# Move to system path (optional)
sudo mv handrive /usr/local/bin/

Linux (ARM64):

curl -L https://handrive.app/download/linux-arm64 -o handrive
chmod +x handrive
sudo mv handrive /usr/local/bin/

Authentication

Before running headless, you must authenticate. This requires running both the server and auth commands:

# Terminal 1: Start the server
handrive serve

# Terminal 2: Authenticate with email OTP
handrive auth login otp your@email.com

# You'll be prompted to enter the OTP sent to your email
# Enter OTP code: 123456
#
# Login successful!
# Email: your@email.com
# User ID: usr_abc123def456

Systemd Service (Recommended)

For production deployments, use systemd for automatic start and restart.

Create /etc/systemd/system/handrive.service:

[Unit]
Description=Handrive File Sharing Service
After=network-online.target
Wants=network-online.target

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

# Security hardening
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=read-only
ReadWritePaths=/home/handrive/.config/handrive
ReadWritePaths=/home/handrive/shares

[Install]
WantedBy=multi-user.target

Create a dedicated user and enable the service:

# Create system user
sudo useradd -r -m -s /bin/false handrive

# Create directories
sudo mkdir -p /home/handrive/.config/handrive
sudo mkdir -p /home/handrive/shares
sudo chown -R handrive:handrive /home/handrive

# Authenticate as handrive user (with server running)
sudo -u handrive handrive serve &
sudo -u handrive handrive auth login otp your@email.com
# Enter OTP, then stop temporary server
kill %1

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

# Check status
sudo systemctl status handrive

macOS Setup

Download and Install

Download Handrive from the download page or use the command line:

# Apple Silicon (M1/M2/M3/M4)
curl -L https://handrive.app/download/mac-arm64 -o handrive
chmod +x handrive
sudo mv handrive /usr/local/bin/

Authentication

# Terminal 1: Start the server
handrive serve

# Terminal 2: Authenticate
handrive auth login otp your@email.com
# Enter OTP when prompted

Launch Agent (Recommended)

Use launchd to run Handrive automatically on login. Create ~/Library/LaunchAgents/app.handrive.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>app.handrive</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/handrive</string>
        <string>serve</string>
        <string>--port</string>
        <string>3001</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/handrive.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/handrive.error.log</string>
</dict>
</plist>

Load the launch agent:

# Load and start
launchctl load ~/Library/LaunchAgents/app.handrive.plist

# Check status
launchctl list | grep handrive

# View logs
tail -f /tmp/handrive.log

# Stop and unload
launchctl unload ~/Library/LaunchAgents/app.handrive.plist

Mac Mini as Always-On Server

Apple Silicon Mac Mini is an excellent choice for a headless Handrive server:

• Low power consumption (idle: ~5-7W for M1/M2/M4)
• Silent operation with no fans at idle
• Compact form factor
• Runs without display connected

Tip: In System Settings → Energy, disable "Put hard disks to sleep" and enable "Prevent automatic sleeping" for always-on operation.

Windows Setup

Download and Install

Download from the download page or use PowerShell:

# Download
Invoke-WebRequest -Uri "https://handrive.app/download/windows-x64" -OutFile "handrive.exe"

# Move to a permanent location
New-Item -ItemType Directory -Force -Path "C:\Program Files\Handrive"
Move-Item handrive.exe "C:\Program Files\Handrive\handrive.exe"

# Add to PATH (run as Administrator)
[Environment]::SetEnvironmentVariable(
    "Path",
    $env:Path + ";C:\Program Files\Handrive",
    [EnvironmentVariableTarget]::Machine
)

Authentication

# PowerShell Window 1: Start the server
handrive serve

# PowerShell Window 2: Authenticate
handrive auth login otp your@email.com
# Enter OTP when prompted

Windows Service (Recommended)

Use NSSM (Non-Sucking Service Manager) to run Handrive as a Windows service:

# Install NSSM (using winget or download from nssm.cc)
winget install nssm

# Create the service (run as Administrator)
nssm install Handrive "C:\Program Files\Handrive\handrive.exe" "serve --port 3001"

# Configure service
nssm set Handrive AppDirectory "C:\Program Files\Handrive"
nssm set Handrive DisplayName "Handrive File Sharing"
nssm set Handrive Description "P2P file sharing service"
nssm set Handrive Start SERVICE_AUTO_START

# Start the service
nssm start Handrive

# Check status
nssm status Handrive

Task Scheduler Alternative

You can also use Task Scheduler to run Handrive at startup:

1. Open Task Scheduler
2. Create Basic Task → Name: "Handrive Server"
3. Trigger: When the computer starts
4. Action: Start a program
5. Program: C:\Program Files\Handrive\handrive.exe
6. Arguments: serve --port 3001
7. Check "Run whether user is logged on or not"

Windows Server Notes

For Windows Server deployments:

• Consider running as a domain service account
• Configure Windows Firewall to allow the Handrive port
• Use Windows Event Log for monitoring (NSSM supports this)

Running Headless

Basic Command (All Platforms)

handrive serve

With Custom Port

handrive serve --port 8080

Verify Authentication Status

handrive auth status

# Output:
# Logged in as: your@email.com
# User ID: usr_abc123def456
# Device ID: dev_xyz789

Quick Background Methods

For testing or quick setups (production deployments should use the service methods above):

Linux/macOS (nohup):

nohup handrive serve > /var/log/handrive.log 2>&1 &

Linux/macOS (screen):

screen -S handrive
handrive serve
# Press Ctrl+A, then D to detach

Linux/macOS (tmux):

tmux new -s handrive
handrive serve
# Press Ctrl+B, then D to detach

Windows (PowerShell background job):

Start-Job -ScriptBlock { handrive serve }
# Use Get-Job and Stop-Job to manage

Troubleshooting

Common Issues

• Not logged in: Run handrive auth login otp while the server is running
• Permission denied: Check directory ownership and permissions
• Port in use: Choose a different port with --port

Checking Service Status

Linux (systemd):

sudo systemctl status handrive
journalctl -u handrive -n 50 --no-pager

macOS (launchd):

launchctl list | grep handrive
tail -f /tmp/handrive.log

Windows (NSSM):

nssm status Handrive
Get-EventLog -LogName Application -Source Handrive -Newest 20

Check Port Listening

Linux/macOS:

lsof -i :3001
# or
ss -tlnp | grep 3001

Windows:

netstat -an | findstr 3001

Check Authentication Status

# While server is running
handrive auth status

See Also

• CLI Reference — All command-line options
• MCP Guide — MCP server configuration
• Troubleshooting — General troubleshooting