haloyd

Complete reference for haloyd server commands.

These commands run on the server to manage the Haloy daemon.

Commands

serve

Start the haloyd daemon. This is typically run by systemd or another init system.

# Start the daemon (foreground)
haloyd serve

# Start with debug logging
haloyd serve --debug

Options:

  • --debug - Enable debug mode with verbose logging

Note: In production, this command is run by the init system (systemd, OpenRC, etc.) rather than manually.

init

Initialize haloyd configuration and directories. Run this during first-time setup.

# Initialize with API domain and TLS
sudo haloyd init --api-domain haloy.example.com

# Initialize without API domain (localhost only)
sudo haloyd init

# Initialize with custom directories
sudo haloyd init --data-dir /custom/data --config-dir /custom/config

Options:

  • --api-domain <domain> - Domain for Haloy API with TLS
  • --data-dir <path> - Custom data directory (default: /var/lib/haloy)
  • --config-dir <path> - Custom config directory (default: /etc/haloy)

What init creates:

  • /etc/haloy/haloyd.yaml - Daemon configuration
  • /etc/haloy/.env - API token
  • /var/lib/haloy/ - Data directory
  • haloy Docker network

config

Get or set configuration values.

# Get a configuration value
sudo haloyd config get api-domain
sudo haloyd config get api-token

# Set a configuration value
sudo haloyd config set api-domain haloy.newdomain.com

Subcommands:

  • get <key> - Get a configuration value
  • set <key> <value> - Set a configuration value

Available keys:

  • api-domain - The domain for the Haloy API
  • api-token - The API authentication token

upgrade

Self-update haloyd to the latest version.

# Upgrade to latest version
sudo haloyd upgrade

# Upgrade to specific version
sudo haloyd upgrade --version 1.2.0

Options:

  • --version <version> - Upgrade to a specific version instead of latest

The upgrade command will:

  1. Download the new binary
  2. Verify the download
  3. Replace the current binary
  4. Signal the service to restart (if running under systemd)

verify

Verify the haloyd installation and check system health.

sudo haloyd verify

Checks performed:

  • Configuration directory exists and is readable
  • Data directory exists and is writable
  • Configuration files are valid
  • Docker daemon is accessible
  • Docker network exists
  • API is responding (if running)

Example output:

✓ Config directory: /etc/haloy
✓ Data directory: /var/lib/haloy
✓ Config file: /etc/haloy/haloyd.yaml
✓ Docker connectivity
✓ Docker network: haloy
✓ API health check

version

Display the haloyd version.

haloyd version

Outputs only the version number in plaintext (e.g., 1.0.0).

Configuration File

The haloyd configuration file is located at /etc/haloy/haloyd.yaml:

api_domain: haloy.example.com
health_monitor:
enabled: true
interval: "15s"
fall: 3
rise: 2
timeout: "5s"

Configuration Options

OptionDescriptionDefault
api_domainDomain for the haloyd API(none)
health_monitor.enabledEnable background health monitoringtrue
health_monitor.intervalTime between health checks15s
health_monitor.fallFailures before marking unhealthy3
health_monitor.riseSuccesses before marking healthy2
health_monitor.timeoutTimeout for each health check5s

Service Management

haloyd runs as a system service. Use your init system to manage it:

Systemd

# Start
sudo systemctl start haloyd

# Stop
sudo systemctl stop haloyd

# Restart
sudo systemctl restart haloyd

# Status
sudo systemctl status haloyd

# View logs
sudo journalctl -u haloyd -f

OpenRC

# Start
sudo rc-service haloyd start

# Stop
sudo rc-service haloyd stop

# Restart
sudo rc-service haloyd restart

# Status
sudo rc-service haloyd status

Exit Codes

The haloyd CLI uses consistent exit codes:

  • 0 - Success
  • 1 - Any error

Next Steps