Running HeliosLogs (CLI)

HeliosLogs runs as a single long-lived process — helios serve. One binary serves the HTTP API, web UI, MCP endpoint, ingestion endpoints, and all background workers.

Global flags

These apply to the helios binary:

Flag	Default	Description
--data-dir <path>	./data	Local directory for block partitions, the single-node control plane, and (by default) the generated key files.
--verbose	off	Extra diagnostics, including periodic memory stats during serve.

serve — run the server

Starts the HTTP API, web UI, MCP endpoint, ingestion endpoints, and all background workers.

helios serve \
  --port 7300 \
  --host 127.0.0.1 \
  --data-dir ./data \
  --frontend-dir ./frontend/dist

Flag	Default	Description
--port <n>	7300	HTTP/MCP listen port.
--host <addr>	127.0.0.1	Bind address. Use 0.0.0.0 to accept non-local connections (containers, LAN, behind a proxy).
--shared-store <uri>	—	Shared object store for multi-node replication and DR: a filesystem/NFS path or s3://bucket/prefix. Omit for single-node, local-only. See Multi-node.
--frontend-dir <path>	—	Built SPA directory (e.g. frontend/dist), served at /. Must contain index.html or serve refuses to start.
--syslog-port <n>	—	Override the syslog listener port (UDP + TCP) from the control plane. 0 disables the listener. Also settable via HELIOS_SYSLOG_PORT. See Syslog.

Exposing HeliosLogs

--host 0.0.0.0 makes HeliosLogs reachable from the network. Put it behind a TLS-terminating reverse proxy and review Security hardening first — HeliosLogs speaks plain HTTP and does not terminate TLS itself.

Logs are written to stderr. Configure verbosity with the standard RUST_LOG environment variable (for example RUST_LOG=info,hyper=warn, the default).

Running as a service

For bare-metal deployments, run serve under a process supervisor. A minimal systemd unit:

[Unit]
Description=HeliosLogs
After=network.target

[Service]
ExecStart=/usr/local/bin/helios serve --host 0.0.0.0 --port 7300 \
  --data-dir /var/lib/helios/data --frontend-dir /usr/local/share/helios/dist
Environment=HELIOS_CONTROL_KEY_PATH=/etc/helios/secret-control.json
Environment=HELIOS_JWT_SECRET_PATH=/etc/helios/secret-jwt.json
Restart=on-failure
User=helios

[Install]
WantedBy=multi-user.target

Keep the data directory and the two secret files on persistent storage. See Secrets & encryption and the Configuration reference.