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 hand serve command. It provides:

• HTTP API Server: REST API access for automation and integration
• MCP Server: Model Context Protocol support for AI assistants (via hand 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.ai/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.ai/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
hand serve

# Terminal 2: Authenticate with email OTP
hand 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

Install as Service (Recommended)

Use the built-in hand service command to install Handrive as a system service:

# Install and start the service
hand service install
hand service start

# Check status
hand service status

The service starts automatically on boot. See the service command documentation for more options.

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.ai/download/mac-arm64 -o handrive
chmod +x handrive
sudo mv handrive /usr/local/bin/

Authentication

# Terminal 1: Start the server
hand serve

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

Install as Service (Recommended)

Use the built-in hand service command to install Handrive as a launch agent:

# Install and start the service
hand service install
hand service start

# Check status
hand service status

The service starts automatically on login. See the service command documentation for more options.

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.ai/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
hand serve

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

Install as Service (Recommended)

Use the built-in hand service command to install Handrive as a scheduled task:

# Install and start the service
hand service install
hand service start

# Check status
hand service status

The service starts automatically on login. See the service command documentation for more options.

Windows Server Notes

For Windows Server deployments:

• Configure Windows Firewall to allow the Handrive port
• Use Windows Event Log for monitoring

Running Headless

Basic Command (All Platforms)

hand serve

With Custom Port

hand serve --port 8080

Verify Authentication Status

hand 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 hand serve > /var/log/handrive.log 2>&1 &

Linux/macOS (screen):

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

Linux/macOS (tmux):

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

Windows (PowerShell background job):

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

Local Cluster

Run multiple Handrive instances on a single machine to maximize hardware utilization:

# Multiple REST API servers
hand serve --port 4263
hand serve --port 4264

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

All instances share state automatically. Changes in one appear instantly in others.

See the Clustering documentation for multi-instance service setup.

Troubleshooting

Common Issues

• Not logged in: Run hand 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

Use the built-in service command on all platforms:

hand service status

For system-level logs:

• Linux: journalctl --user -u handrive
• macOS: Console.app or log show --predicate 'processImagePath contains "hand"'
• Windows: Event Viewer

Check Port Listening

Linux/macOS:

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

Windows:

netstat -an | findstr 4263

Check Authentication Status

# While server is running
hand auth status

See Also

• CLI Reference — All command-line options
• MCP Guide — MCP server configuration
• Clustering Architecture — Multi-device and multi-instance scaling
• Troubleshooting — General troubleshooting