Quick Start

Prerequisites

• Python 3.13+
• uv package manager (recommended) or pip

Installation

From source (current)

git clone https://github.com/seerflow/seerflow.git
cd seerflow
uv sync

From PyPI (coming soon)

pip install seerflow
# or
uv add seerflow

First Run

Seerflow works out of the box with zero configuration:

uv run python -m seerflow

This starts Seerflow with:

• SQLite storage (WAL mode, auto-created at ~/.local/share/seerflow/seerflow.db)
• Syslog receiver on UDP 514 and TCP 601
• OTLP receiver on gRPC 4317 and HTTP 4318
• Dashboard on port 8080

Configuration

Create seerflow.yaml in your working directory:

storage:
  backend: sqlite  # or postgresql
  sqlite_path: ./data/seerflow.db

receivers:
  syslog_enabled: true
  syslog_udp_port: 514
  otlp_grpc_enabled: true
  otlp_grpc_port: 4317

detection:
  hst_window_size: 1000
  hst_n_trees: 25

log_level: INFO

Environment variables are supported with ${VAR:-default} syntax:

storage:
  postgresql_url: ${DATABASE_URL:-postgresql://localhost/seerflow}

Run Tests

uv run pytest --cov=src/seerflow -v

Quality Gates

uv run ruff check .           # lint
uv run ruff format --check .  # format
uv run mypy src/              # type check
uv run bandit -r src/ -c pyproject.toml  # security

Next Steps

• Read the Architecture Overview to understand how Seerflow processes logs
• Check the Storage documentation for backend configuration
• See the Configuration Reference for all options