Server Mode
lynxdb server runs LynxDB as an HTTP server. It stores events on disk,
accepts data from the CLI, the REST API and log shippers, and answers
PPL queries.
Start the server
# Defaults: listen on localhost:3100, data in ~/.local/share/lynxdb
lynxdb server
# Another data directory
lynxdb server --data-dir /var/lib/lynxdb
# Listen on all interfaces
lynxdb server --addr 0.0.0.0:3100
# A temporary data directory, deleted when the server exits (for tests)
lynxdb server --data-dir ""
On startup the server prints where its settings come from:
Config /home/user/.config/lynxdb/config.yaml
Data /var/lib/lynxdb
Listen localhost:3100
time=2026-11-17T16:41:03.285+01:00 level=INFO msg="starting LynxDB" version=dev addr=localhost:3100 config=/home/user/.config/lynxdb/config.yaml
time=2026-11-17T16:41:03.287+01:00 level=INFO msg="API server started" addr=127.0.0.1:3100
An Overrides line lists the environment variables and flags that changed
settings. The server also starts an OTLP/HTTP log receiver on port 4318. See
Server configuration for every flag and setting.
Each index is a directory under indexes/ in the data directory, created with the
index's first events. See Storage for what the
files hold.
--auth needs a data directory: API keys are stored in it. With
--data-dir "" the server runs without authentication.
Ingest data
From the CLI
# A log file
lynxdb ingest access.log --source web-01
# With a source type and a target index
lynxdb ingest access.log --source web-01 --sourcetype nginx --index web
# Standard input
kubectl logs deploy/api --since=1h | lynxdb ingest --source k8s-api
lynxdb ingest sends lines in batches of 5000 (--batch-size) to
POST /api/v1/ingest/raw and prints the event count and rate when done.
From the REST API
# Structured events: NDJSON, one JSON object per line, stored as they are
printf '%s\n' \
'{"message":"user login","source":"auth-api","user_id":42,"level":"info"}' \
'{"message":"connection refused","source":"api","service":"redis","level":"error"}' |
curl -X POST localhost:3100/api/v1/ingest --data-binary @-
# Raw lines, one event per line
echo '192.168.1.1 - - [14/Feb/2026:14:23:01 +0000] "GET /api HTTP/1.1" 200 1234' | \
curl -X POST localhost:3100/api/v1/ingest/raw \
-H 'X-Source: nginx' \
--data-binary @-
{"data":{"accepted":2,"failed":0}}
/api/v1/ingest writes to the index in ?index= or the X-Index header,
main by default. /api/v1/ingest/raw extracts the leading timestamp and
key=value pairs of text lines and keeps the text in _raw. The server
writes ingested events to disk within a second (storage.flush_interval),
and before every query, so a query sees every event ingested before it.
Log shippers connect through the Elasticsearch _bulk API, OTLP, Splunk HEC
or syslog. See Ingest Data.
Query data
CLI
lynxdb query sends the query to the server at http://localhost:3100
(--server or LYNXDB_SERVER changes it):
# Search
lynxdb query 'source=main level=ERROR'
# Aggregate
lynxdb query 'source=main level=ERROR | stats count() as errors by host | sort - errors'
# Time range
lynxdb query 'source=main level=ERROR | stats count()' --since 1h
# Output formats
lynxdb query 'source=main level=ERROR | stats count() by host' --format table
lynxdb query 'source=main level=ERROR | stats count() by host' --format csv > report.csv
REST API
curl -s -X POST localhost:3100/api/v1/query \
-H 'Content-Type: application/json' \
-d '{"q": "source=main level=ERROR | stats count() as errors by host | sort - errors | head 3"}'
{"data":{"type":"aggregate","columns":["errors","host"],"rows":[[67,"api-02"],[58,"web-02"],[57,"web-03"]],"total_rows":3,"has_more":false},"meta":{"took_ms":0.1,"query_id":"qry_a3938b4846474ae2","rows":3}}
POST /api/v1/query/stream returns one JSON object per row, then a
__meta line:
curl -s -X POST localhost:3100/api/v1/query/stream \
-H 'Content-Type: application/json' \
-d '{"q": "source=main level=ERROR | sort _time | fields _time, host, status | head 2"}'
{"_time":"2025-01-15T08:00:00.105Z","host":"web-03","status":502}
{"_time":"2025-01-15T08:00:00.543Z","host":"api-02","status":502}
{"__meta":{"total":2,"took_ms":0}}
See the Query API for jobs and errors.
Inspect the server
lynxdb status # uptime, storage, events, parts, indexes
lynxdb health # health check, for scripts and load balancers
lynxdb indexes # indexes with their events, bytes, parts and time span
lynxdb fields # field catalog: each field and the indexes that hold it
LynxDB dev — uptime 0m — healthy
Storage 48.6 KB
Events 1,036 total
Parts 3
Indexes 2
Indexes main (97%), web (3%)
Oldest 2025-01-15T08:00:00Z
Newest 2026-11-17T15:54:45Z
Run as a service
systemd
# /etc/systemd/system/lynxdb.service
[Unit]
Description=LynxDB log analytics
After=network.target
[Service]
Type=simple
User=lynxdb
ExecStart=/usr/local/bin/lynxdb server --data-dir /var/lib/lynxdb
Restart=on-failure
LimitNOFILE=65536
[Install]
WantedBy=multi-user.target
sudo useradd --system --home /var/lib/lynxdb --shell /usr/sbin/nologin lynxdb
sudo mkdir -p /var/lib/lynxdb && sudo chown lynxdb:lynxdb /var/lib/lynxdb
sudo systemctl daemon-reload
sudo systemctl enable --now lynxdb
Docker
docker run -d --name lynxdb \
-p 3100:3100 \
-v lynxdb-data:/data \
ghcr.io/lynxbase/lynxdb server --addr 0.0.0.0:3100 --data-dir /data
See Single-node deployment and Docker deployment.
Configuration
Create a config file with every setting commented out:
lynxdb config init
It is written to ~/.config/lynxdb/config.yaml. Uncomment the lines to
change, for example:
listen: "localhost:3100"
data_dir: "~/.local/share/lynxdb"
retention: "7d"
log_level: "info"
storage:
partition: "24h"
lynxdb config validate checks the file and lynxdb config reload applies
it to a running server. See the
Configuration Reference.
Next steps
- Your First Query: PPL basics
- Ingest Data: every ingestion path
- Configuration: tune the server
- Single-node deployment: production setup