haloyd

Complete reference for haloyd server commands. haloyd is the control plane: it handles deployments, Docker discovery, health checks, certificates, and the API. Public HTTP/HTTPS traffic is served by the separate haloy-proxy service.

These commands run on the server to manage the Haloy daemon. Examples assume a root shell; if you’re using a sudo user, run sudo -i first or prefix privileged commands with sudo.

Commands

serve

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

# Start the daemon (foreground)
haloyd serve

# Start with debug logging
haloyd serve --debug
# 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
haloyd init --api-domain haloy.example.com

# Initialize without API domain (localhost only)
haloyd init

# Initialize with custom directories
haloyd init --data-dir /custom/data --config-dir /custom/config
# Initialize with API domain and TLS
haloyd init --api-domain haloy.example.com

# Initialize without API domain (localhost only)
haloyd init

# Initialize with custom directories
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

haloyd init does not install the haloy-proxy service. Use the install script for normal server setup, or install both services manually as described in Server Installation.

config

Get or set configuration values.

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

# Set a configuration value
haloyd config set api-domain haloy.newdomain.com
# Get a configuration value
haloyd config get api-domain
haloyd config get api-token

# Set a configuration value
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

verify

Verify the haloyd installation and check system health.

haloyd verify
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
✓ 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
haloyd version

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

To check both server components from your local machine, use haloy server version.

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"
api_domain: haloy.example.com
health_monitor:
  enabled: true
  interval: "15s"
  fall: 3
  rise: 2
  timeout: "5s"

Configuration Options

Option	Description	Default
`api_domain`	Domain for the haloyd API	(none)
`health_monitor.enabled`	Enable background health monitoring	`true`
`health_monitor.interval`	Time between health checks	`15s`
`health_monitor.fall`	Failures before marking unhealthy	`3`
`health_monitor.rise`	Successes before marking healthy	`2`
`health_monitor.timeout`	Timeout for each health check	`5s`

Service Management

haloyd and haloy-proxy run as separate system services. Restarting haloyd does not restart the proxy, so application traffic keeps flowing while the control plane restarts.

Systemd

# Start
systemctl start haloy-proxy haloyd

# Stop
systemctl stop haloyd haloy-proxy

# Restart only the control plane
systemctl restart haloyd

# Status
systemctl status haloyd haloy-proxy

# View control-plane logs
journalctl -u haloyd -f

# View proxy logs
journalctl -u haloy-proxy -f
# Start
systemctl start haloy-proxy haloyd

# Stop
systemctl stop haloyd haloy-proxy

# Restart only the control plane
systemctl restart haloyd

# Status
systemctl status haloyd haloy-proxy

# View control-plane logs
journalctl -u haloyd -f

# View proxy logs
journalctl -u haloy-proxy -f

OpenRC

# Start
rc-service haloy-proxy start
rc-service haloyd start

# Stop
rc-service haloyd stop
rc-service haloy-proxy stop

# Restart only the control plane
rc-service haloyd restart

# Status
rc-service haloyd status
rc-service haloy-proxy status
# Start
rc-service haloy-proxy start
rc-service haloyd start

# Stop
rc-service haloyd stop
rc-service haloy-proxy stop

# Restart only the control plane
rc-service haloyd restart

# Status
rc-service haloyd status
rc-service haloy-proxy status

Exit Codes

The haloyd CLI uses consistent exit codes:

0 - Success
1 - Any error