hand serve

Start the Handrive HTTP server for headless operation.

Synopsis

hand serve [OPTIONS]

Description

The serve command starts the Handrive HTTP server, enabling headless operation. The server provides a REST API for all Handrive operations and must be running for other CLI commands to work.

The server starts immediately regardless of authentication state. Protected endpoints return 401 until the user logs in via hand auth.

Options

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

Environment Variables

Variable	Description	Default
`API_HOST`	IP address to bind to	`127.0.0.1`
`API_PORT`	Port to listen on (overridden by --port)	`4263`

Examples

Start with default settings

hand serve

Start on a custom port

hand serve --port 9000

Listen on all interfaces

# Bind to all network interfaces (accessible from other machines)
API_HOST=0.0.0.0 hand serve

# Combine with custom port
API_HOST=0.0.0.0 hand serve --port 8080

Run in background

# Unix/macOS
hand serve &

# Or use nohup for persistence
nohup hand serve > /var/log/handrive.log 2>&1 &

Systemd service

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

[Service]
Type=simple
User=handrive
Environment="API_HOST=0.0.0.0"
ExecStart=/usr/local/bin/hand serve --port 4263
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

REST API

When running, the server exposes a REST API at http://127.0.0.1:4263 (or your configured host/port).

Key endpoints:

GET /api/auth/status - Authentication status
GET /api/shares - List shares
GET /api/shares/:id/files - List files
GET /api/transfers - List transfers
GET /docs - OpenAPI documentation (Swagger UI)