Install (Windows/WSL)

HeliosLogs is a Linux/macOS binary — there's no native Windows .exe. On Windows you run it inside WSL2 (Windows Subsystem for Linux), using the same apt package as a Linux server. Localhost forwarding means you still open the UI from your Windows browser at http://localhost:7300.

Prefer containers? Docker Desktop (with the WSL2 backend) runs the published image unchanged — see the Quickstart and Docker & images. For a real Linux host see Install (Linux); on a Mac see Install (macOS).

Prerequisites

• Windows 11, or Windows 10 version 2004+ (build 19041+).
• WSL2 with a Linux distribution. The steps below assume Ubuntu (the default), so they use apt. For a Fedora/RHEL-family distro under WSL, follow the dnf instructions instead.

If you don't have WSL yet, install it from an admin PowerShell, then reboot:

wsl --install            # installs WSL2 + Ubuntu by default
wsl --list --verbose     # confirm the distro is VERSION 2

Launch Ubuntu from the Start menu (or run wsl in a terminal) and create your Linux user when prompted. Everything below runs inside that Ubuntu shell.

Enable systemd (recommended)

HeliosLogs installs a systemd service. WSL2 supports systemd, but it's off unless you opt in. Inside the Ubuntu shell, enable it:

sudo tee /etc/wsl.conf >/dev/null <<'CONF'
[boot]
systemd=true
CONF

Then, from a Windows PowerShell/Command Prompt, restart the distro so the change takes effect:

wsl --shutdown

Reopen Ubuntu and verify systemd is running:

systemctl is-system-running     # "running" or "degraded" is fine

No systemd? Run it in the foreground

If you'd rather not enable systemd, skip the service and run HeliosLogs directly — see Run without a service below.

Install

Trust the signing key, add the repo (once), then install — identical to Debian/Ubuntu on Linux:

sudo install -d /etc/apt/keyrings
curl -fsSL https://helioslogs.github.io/apt/helioslogs.gpg \
  | sudo tee /etc/apt/keyrings/helioslogs.gpg >/dev/null
echo "deb [signed-by=/etc/apt/keyrings/helioslogs.gpg] https://helioslogs.github.io/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/helioslogs.list >/dev/null
sudo apt-get update
sudo apt-get install -y helioslogs

(Optional) Bootstrap the admin account

On an empty install the first browser visitor completes a one-time setup wizard. To skip that, set credentials in the service config before the first start:

sudo install -d /etc/helioslogs
sudo cp /usr/share/helioslogs/helioslogs.env.example /etc/helioslogs/helioslogs.env
sudoedit /etc/helioslogs/helioslogs.env
#   [email protected]
#   HELIOS_ADMIN_PASSWORD=change-me

Enable and start

sudo systemctl enable --now helioslogs
systemctl status helioslogs --no-pager

Verify it's up:

helioslogs --version
curl -s http://localhost:7300/api/health        # {"ok":true}

Open it from Windows

WSL2 forwards localhost from Windows into the distro, so just open http://localhost:7300 in your Windows browser and log in (or complete the setup wizard). Next: First steps.

Reachable from your LAN

The packaged service binds to 0.0.0.0:7300 inside WSL. Windows still reaches it over the forwarded localhost; whether other machines can connect depends on your Windows firewall and any port-proxy you add. Read Security hardening and put HeliosLogs behind TLS / a reverse proxy before exposing it beyond your PC.

Run without a service

If you skipped systemd, run HeliosLogs in the foreground from the Ubuntu shell:

helioslogs serve --port 7300 --data-dir ~/.helioslogs/data
# listening on http://0.0.0.0:7300

It stops when you close the shell. Keep the keys in ~/.helioslogs (or wherever you point HELIOS_CONTROL_KEY_PATH / HELIOS_JWT_SECRET_PATH) and back them up — see Secrets & encryption.

Syslog listener (optional)

Separately from the HTTP port (7300), HeliosLogs can receive raw syslog over UDP + TCP on its own port — default 5514. The listener is off by default; turn it on under Admin → Data Ingestion → Syslog. Set HELIOS_SYSLOG_PORT in /etc/helioslogs/helioslogs.env to change it. Reaching the listener from outside Windows needs a netsh interface portproxy rule plus a firewall opening — see Syslog.

Where things live

Inside the WSL distro the layout matches the Linux package:

Path (inside WSL)	Contents
/usr/bin/helioslogs	The binary.
/lib/systemd/system/helioslogs.service	The service unit.
/etc/helioslogs/helioslogs.env	Service config (admin bootstrap, HELIOS_SYSLOG_PORT, RUST_LOG, …).
/var/lib/helioslogs	Data partitions, control plane, and the auto-generated secret keys.

From Windows, browse the distro's files at \\wsl$\Ubuntu\var\lib\helioslogs. Keep data on the WSL ext4 filesystem (not a /mnt/c Windows path) for performance.

Upgrade

The package upgrades in place; /var/lib/helioslogs is preserved.

sudo apt-get update && sudo apt-get install --only-upgrade helioslogs
sudo systemctl restart helioslogs

See Upgrades & backups for backup guidance and version policy.

Uninstall

sudo systemctl disable --now helioslogs
sudo apt-get remove helioslogs

Removing the package leaves your data in /var/lib/helioslogs. Delete it manually for a clean slate, or remove the whole distro from Windows with wsl --unregister Ubuntu.