homer eleven

May 12, 2026 · View on GitHub

homer eleven

100% Opensource Telecom Observability since 2011

homer is the all-in-one HEP capture and API server monolith powering Homer 11.x data lake

Features

All-in-One Application (Writer, Reader, Coordinator, Compactor, API)
Modern Codebase in golang for X64/ARM64 on Linux/MacOS
Powered by DuckDB 1.5 and Apache Arrow/IPC/Parquet
Datalake design based on DuckLake Catalog and Local/Object Storage
End-to-End Columnar OTLP Design w/ on-demand query execution
Linear Scaling to query over shared Object Storage catalog/pool
Flexible Schema support for growing problems and protocols
Backwards compatible with all HEPv3 Agents
Easy to maintain, operate and scale (down to zero!)
Cloud Native Design for K8s and standard deployments
Built-In User Interface for Humans
MCP support and LLM/Agent friendly design (steal our boring jobs)

Architecture

Homer uses a modular architecture with four main components:

┌─────────────────────────────────────────────────────────────────────────────┐
│                           Homer Core                                        │
│                                                                             │
│  ┌─────────────┐   ┌─────────────┐   ┌──────────┐   ┌─────────────────┐     │
│  │   Ingest    │   │   Storage   │   │   Node   │   │   Coordinator   │     │
│  │  (HEP recv) │──▶│  (DuckLake) │──▶│ gRPC/HTTP│──▶│    (REST API)   │     │
│  └─────────────┘   └─────────────┘   └──────────┘   └─────────────────┘     │
│   UDP/TCP/HTTP      Parquet+S3     Airport :50051     HTTP :8080            │
│                                    FlightSQL :50055  (opt. proxy :32010)    │
└─────────────────────────────────────────────────────────────────────────────┘

Modules

Module	Description
Ingest	Receives HEP packets via UDP/TCP/TLS/HTTP/HTTPS
Storage	Writes data to DuckLake (Parquet + catalog)
Node	Airport gRPC + HTTP `/query`; optional Arrow FlightSQL for Grafana (docs/FLIGHTSQL.md)
Coordinator	REST API gateway for UI and external applications

Quick Start

Install Options

Download a release and install the homer package on your OS/arch
Use the official docker builds and compose examples
Build your own release locally (keep reading)

All-in-One Deployment

{
  "ingest": {
    "enable": true,
    "udp": { "enable": true, "port": 9060 },
    "tcp": { "enable": true, "port": 9061 },
    "http": { "enable": true, "port": 9080 }
  },
  "storage": {
    "enable": true,
    "ducklake": {
      "catalog_path": "/data/homer/homer_catalog.sqlite",
      "data_path": "/data/homer/parquet"
    }
  },
  "node": {
    "enable": true,
    "flight_server": { "port": 50051 }
  },
  "coordinator": {
    "enable": true,
    "http_server": { "port": 8080 }
  }
}

For more storage options consult the available STORAGE POLICIES

Build & Run

# Build
make

# Run as server (default mode)
./homer --config-path /etc/homer/homer.json

# With debug logging
./homer --config-path /etc/homer/homer.json --log-level debug

Subcommands

Homer uses a subcommand-based CLI. Running homer without arguments starts the server.

homer                         Run the server (default)
homer search [flags]          Search Homer data via coordinator API
homer cli [flags]             Interactive DuckLake SQL shell
homer system [flags]          System operations (compaction, extensions, reload)
homer wizard [flags]          Interactive config generator wizard
homer mcp [flags]             Start MCP stdio server
homer version                 Show version
homer help                    Show full help with all flags

Server Mode (default)

homer --config-path /etc/homer/homer.json
homer --config-path /etc/homer/homer.json --log-level debug --syslog-disable

Flag	Description
`--config-path <path>`	Path to config file or directory
`--log-level <level>`	Log level: debug, info, warn, error, trace
`--syslog-disable`	Disable syslog, use only stdout
`--pid-file <path>`	PID file path (default: /var/run/homer-core.pid)

Search (via coordinator API)

Search Homer data from the command line with table, vertical, CSV, JSON, chart, call flow, or PCAP output (SIP only; use --format pcap with -o / --output).

# Basic SIP search (last hour)
homer search --host 10.0.0.1:8081 --user admin --pass secret

# Search INVITE messages with call flow diagram
homer search --host 10.0.0.1:8081 --method INVITE --format callflow

# Export SIP messages to a pcap file (same framing as API /transactions/export/pcap)
homer search --host 10.0.0.1:8081 --call-id "abc123@host" --format pcap -o /tmp/call.pcap

# Search by Call-ID
homer search --host 10.0.0.1:8081 --call-id "abc123@host" --format vertical

# Post-filter: only INVITEs and BYEs, exclude provisional responses
homer search --host 10.0.0.1:8081 --grep "INVITE,BYE" --exclude "100,183"

# Interactive TUI mode
homer search --host 10.0.0.1:8081 --interactive

See docs/SEARCH.md for full documentation and examples.

CLI (DuckLake SQL Shell)

Interactive SQL shell for direct DuckLake queries:

# Start interactive CLI
homer cli --config-path /etc/homer/homer.json

# Execute single query and exit
homer cli --config-path /etc/homer/homer.json --query "SELECT COUNT(*) FROM homer_lake.main.hep_proto_1_call"

Command	Description
`help`, `\h`, `\?`	Show help
`tables`, `\dt`	List available tables
`clear`, `\c`	Clear screen
`exit`, `quit`, `\q`	Exit CLI

System Operations

# Run full compaction
homer system --config-path /etc/homer/homer.json --compaction-force

# Install DuckDB extensions
homer system --config-path /etc/homer/homer.json --install-extensions

# Show DuckDB version
homer system --config-path /etc/homer/homer.json --duckdb-version

# Generate example config
homer system --generate-example-config > homer.json

# Reload running process
homer system --reload

Wizard (Config Generator)

Interactive wizard that generates a complete homer.json config:

# Interactive TUI wizard
homer wizard

# Non-interactive: generate config for a specific deployment profile
homer wizard --profile all-in-one --output homer.json
homer wizard --profile writer --output homer-writer.json
homer wizard --profile coordinator --output homer-coordinator.json
homer wizard --profile edge --output homer-edge.json
homer wizard --profile node --output homer-node.json

Profile	Modules Enabled
`all-in-one`	ingest + storage + node + coordinator
`writer`	ingest + storage
`edge`	ingest + storage + node
`coordinator`	coordinator only
`node`	node only

Configuration Examples

See the examples/ directory:

File	Description
`homer.json`	All-in-one deployment
`homer-writer.json`	Ingest + Storage + Node
`homer-node.json`	Node only (read-only)
`homer-coordinator.json`	Coordinator only
`homer-edge.json`	Edge deployment

Documentation

Search CLI - Search from the command line (examples, formats, call flow)
Config Wizard - Interactive config generator (TUI + presets)
Coordinator Module - REST API gateway
MCP UI Guide - Natural-language query assistant (configuration + UI usage)
Node Module - FlightSQL data server
Storage Architecture - DuckLake storage
Storage Policies - Tiered storage (hot/cold)
Compaction Setup - File compaction

License

Released under the AGPL-3.0 License

Copyright (C) 2025 QXIP BV