hand service

Install and manage Handrive as a system service (daemon).

Synopsis

hand service install [--port <PORT>]
hand service uninstall
hand service start
hand service stop
hand service status

Description

The service command manages Handrive as a system service, allowing it to run automatically in the background. This is the recommended way to run Handrive on servers and headless systems.

macOS: Uses launchd (LaunchAgent)
Linux: Uses systemd (user service)
Windows: Uses Task Scheduler

Subcommands

service install

Install Handrive as a system service.

Option	Description	Default
`-p, --port <PORT>`	Port for the daemon to listen on	`4263`

$ hand service install
Service installed successfully.
Run 'hand service start' to start the daemon.

$ hand service install --port 8080
Service installed on port 8080.

service uninstall

Remove the Handrive system service.

$ hand service uninstall
Service uninstalled successfully.

service start

Start the Handrive daemon service.

$ hand service start
Service started.

service stop

Stop the Handrive daemon service.

$ hand service stop
Service stopped.

service status

Check if the Handrive daemon is running.

$ hand service status
Handrive service is running (PID: 12345)

$ hand service status
Handrive service is not running

Examples

Quick setup

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

# Verify it's running
hand service status

# Login (required once)
hand auth login otp your@email.com

Custom port

# Install on a custom port
hand service install --port 9000

# Start the service
hand service start

# Other CLI commands use this port automatically
HANDRIVE_API_URL=http://127.0.0.1:9000 hand shares list

Reinstall with different settings

# Stop and uninstall existing service
hand service stop
hand service uninstall

# Reinstall with new settings
hand service install --port 8080
hand service start

Service Locations

Platform	Service Location
macOS	`~/Library/LaunchAgents/ai.handrive.daemon.plist`
Linux	`~/.config/systemd/user/handrive.service`
Windows	Task Scheduler: `Handrive` task

Notes

The service runs as your user, not as root/administrator
You must authenticate once after installation using hand auth login
The service starts automatically on system boot/login after installation
Logs are available via system logging (journalctl on Linux, Console.app on macOS, Event Viewer on Windows)

Troubleshooting

Service won't start

# Check status for error messages
hand service status

# Try running manually to see errors
hand serve --port 4263

Port already in use

# Uninstall and reinstall on a different port
hand service stop
hand service uninstall
hand service install --port 9000
hand service start

Windows: Check Task Scheduler

# Open Task Scheduler to verify the task exists
# Look for "Handrive" in the Task Scheduler Library

# Or use schtasks to check status
schtasks /query /tn Handrive