Quickstart

The fastest path from nothing to your first search: install or run HeliosLogs, log in, send a few events, and query them.

1. Install and run

Get HeliosLogs listening on :7300 — pick how you want to run it:

Native install

# macOS or Linux — detects your OS, installs the native package (brew/apt/dnf/apk).
curl -fsSL https://www.helioslogs.com/install.sh | sh

# Then start it (the installer prints the exact command for your system):
# sudo systemctl enable --now helioslogs   # Linux service (Alpine: sudo rc-service helioslogs start)
# helioslogs serve --port 7300 --data-dir ./data       # macOS, or a rootless --user install

Docker

docker pull helioslogs/helioslogs:latest

docker run -p 7300:7300 \
  -v helios-data:/app/data \
  -v helios-secret:/app/secret \
  helioslogs/helioslogs:latest

Podman

podman pull docker.io/helioslogs/helioslogs:latest

podman run -p 7300:7300 \
  -v helios-data:/app/data \
  -v helios-secret:/app/secret \
  docker.io/helioslogs/helioslogs:latest

Linux (dnf)

# Fedora / RHEL / CentOS Stream / AlmaLinux / Rocky / Amazon Linux.
sudo dnf install -y dnf-plugins-core
sudo dnf copr enable helioslogs/helioslogs
sudo dnf install -y helioslogs
sudo systemctl enable --now helioslogs       # starts the service on :7300

Linux (apt)

# Debian / Ubuntu — trust the signing key + add the repo (once), then install.
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
sudo systemctl enable --now helioslogs       # starts the service on :7300

Homebrew

# macOS (or Linuxbrew) — picks the right build for your machine.
brew install helioslogs/tap/helioslogs
helioslogs serve --port 7300 --data-dir ./data

Windows (WSL)

# In an Ubuntu (WSL2) shell — same apt repo as 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
sudo systemctl enable --now helioslogs       # needs systemd in WSL2 — see the guide

Native install for more details see Install (Linux) · Install (macOS) · Install (Windows/WSL).

Containers to scale out see Docker & images (Compose, restart policies) or Kubernetes.

Receiving syslog (containers)

Add -p 5514:5514/udp -p 5514:5514/tcp to the run command to accept raw syslog. The listener is off by default — enable it under Admin → Data Ingestion → Syslog. See Syslog.

2. Log in

Open http://localhost:7300. On a fresh install you'll see a one-time setup wizard — the first visitor claims the instance by creating the admin account.

3. Send your first events

HeliosLogs accepts newline-delimited JSON (NDJSON) — one event per line — on POST /api/ingest. Each event routes to a (env, index, day) partition by its timestamp:

curl -X POST 'http://localhost:7300/api/ingest?env=default&index=adhoc' \
  --data-binary @- <<'JSON'
{"timestamp":"2026-06-14T18:00:00Z","level":"INFO","service":"web","message":"hello from curl"}
{"timestamp":"2026-06-14T18:00:01Z","level":"ERROR","service":"web","message":"goodbye","error_type":"DeadlineExceeded","status":504}
JSON
# {"ingested":2,"errors":0}

You don't have to declare any of those fields first — level, service, error_type, and status are all immediately queryable. That's schema-on-read.

4. Or load sample data

Prefer to explore with a realistic dataset? On a fresh install the search page offers a Load sample data button (an admin action that ingests a generated set of events). Click it and HeliosLogs will poll until the data appears.

5. Run your first searches

Go to Search and try these, picking a time range (top-right) that covers your events:

Query	Finds
error	events containing "error" anywhere in the message
level:ERROR	events whose level field is ERROR
service:web status:504	implicit AND across two fields
level:ERROR | stats count by service	error counts per service (table mode)

Click a field value in the left field panel to filter by it; drag across the histogram to zoom into a time window.

Where to go next

• Understand the model: Core concepts
• Get real data flowing: Ingestion overview
• Learn the query language: Query language
• Set up your team: First steps and Users & RBAC