Nerdlog: a remote-first TUI log viewer that keeps log analysis on the servers

The problem Nerdlog targets: reading logs across hosts without a log server

The README is explicit about the origin: a web service backend running as systemd services on a set of Linux instances, printing a lot of logs, and a team that wanted to read those logs efficiently with a timeline histogram, the way Graylog or Kibana present one. The alternative they were replacing was a Splunk setup the README calls painfully slow.

The design decision that follows from that origin is the absence of a central server. Nerdlog does not ship an indexer, a database, or an ingest pipeline. It opens an SSH connection to every node you name and keeps those connections idle in the background. Log analysis happens on the remote nodes. On each query, only up to 250 messages per logstream (the README says this is configurable) plus histogram data come back over the wire, and most of that traffic is gzipped.

That makes it a tool for a specific reader: someone who already has SSH access to the machines, who is comfortable in a terminal, and who wants a quick visual answer about when something happened rather than a durable search index. It is not a replacement for centralized retention, alerting, or compliance archiving. The README points to a docs/limitations.md file and acknowledges that a separate server to store log files might still help in some cases, which is an honest admission that the remote-first model has an edge case where a central store is still useful.

How the SSH fan-out and the 250-message window actually work

A logstream is the unit of work. The README defines it as a contiguous stream of log messages on a particular server reachable via SSH, or on the local server. Two kinds exist today: one or more consecutive log files (the README notes that at most two files can currently be in a logstream, with the limitation expected to be removed), and output from journalctl.

Logstreams are written in a compact address form. A bare [email protected] means the default log file on the default SSH port. A fuller form adds the port and a path: [email protected]:1234:/some/other/logfile. Passing journalctl as the log file selects journalctl explicitly. Several logstreams are comma separated.

The client also reads ~/.ssh/config and can take port, username and hostname from there. It supports globs, so hosts named myhost-01 and myhost-02 in the SSH config can be addressed as myhost-*. Because SSH config cannot express which log file to read, per-host log file choices go in Nerdlog's own config file, ~/.config/nerdlog/logstreams.yaml, whose top-level key is log_streams.

The default resolution order matters for what you see. Nerdlog prefers /var/log/messages (with the older /var/log/messages.1), then /var/log/syslog (with /var/log/syslog.1), and falls back to journalctl only if neither file is available. The README gives the reason plainly: journalctl is less reliable and much slower. It also notes there is currently no option to prefer journalctl by default. That is a real constraint if your distribution has moved to journal-only logging, because you will be relying on the fallback path rather than a first-class preference.

The arbitrary-command support is worth calling out. Nerdlog can use an arbitrary command to establish the shell session with remote hosts, which the README says allows use with Teleport or similar tools. That is the escape hatch for environments where direct SSH is not how you reach machines.

Installing Nerdlog and running a first multi-host query

The README says the easiest route is a prebuilt binary from the releases page. Building from source needs Go. On Linux, the X11 dev package is also required because of clipboard access; the README gives the Ubuntu command:

sudo apt install libx11-dev

On macOS and Windows no extra dependencies are required, though the README states that only the client can run on Windows and that Windows hosts cannot be used as log sources.

If you prefer go install, the README documents two forms. The first tracks the latest release and may miss features not yet officially released:

go install github.com/dimonomid/nerdlog/cmd/nerdlog@latest

Unless GOPATH or GOBIN is customized, the binary lands in $HOME/go/bin. There is also a make path that builds into bin/nerdlog and can install to /usr/local/bin:

make && sudo make install

Or build and run without installing:

make && bin/nerdlog

Running the binary opens a query edit form. The README describes the fields as time range, logstreams, and a few others. For a first real query, point it at one host whose logs you know. If the host is myserver.com reachable on port 22, the logstream is just:

[email protected]

If you need a non-default port and a specific file, the README's explicit form is:

[email protected]:1234:/some/other/logfile

Multiple hosts go in as a comma-separated list, and the README's own example is [email protected], [email protected]:1234:/some/other/logfile. What you should see after submitting is a merged view of messages from every logstream, plus the timeline histogram drawn above or beside them. Because only up to 250 messages per logstream arrive per query, a very busy host will show a window rather than everything; the README says pagination is possible to fetch the next batch.

For hosts that need a non-default log file, the README shows the shape of the logstreams config file, which begins with the top-level log_streams key. The README excerpt does not show the full per-host mapping, so read the file's own documentation before editing it.

Where Nerdlog is the wrong tool

The 250-message cap per logstream per query is the sharpest limitation. It is a deliberate bandwidth trade, and it means Nerdlog is not a way to pull a complete log set down for offline analysis. If your question is "give me every matching line from the last week across forty hosts," this is the wrong instrument.

The second limitation is the journalctl preference gap. Nerdlog defaults to log files and will only reach for journalctl when no /var/log/messages or /var/log/syslog is present. The README states there is currently no option to prefer journalctl. On a distribution where journald is the only logging path, you get the slower, less reliable path by default, and the README's own FAQ explains why the tool avoids it.

The third is the logstream file limit: at most two consecutive files per logstream today. If your retention rotates through many files, a single logstream will not span all of them.

The fourth is platform asymmetry. Windows can run the client but cannot be a source. If your fleet is mixed, the Windows machines are simply invisible to Nerdlog.

Finally, there is no central store of results. Two engineers running the same query get two independent sessions. Nothing is shared, nothing is retained, and nothing is auditable after the fact. Teams that need a common, revisitable record of what was searched are outside the design.

The README is candid that the code still has traces of its hackathon origins and could be more polished, while also stating the author considers it ready for production use. Both statements can be true; the honest reading is that the tool is used in production by its author, and the polish level is uneven.

How it differs from Klogg, Lazyjournal and centralized stacks

Klogg is a desktop log viewer built around opening files locally and searching them. The difference in approach is where the bytes live. Klogg reads files you can open; Nerdlog never brings the file over. It runs the filtering remotely and returns a bounded slice plus histogram data. If your logs already sit on your laptop, Klogg's model is simpler. If they sit on thirty servers you reach by SSH, Nerdlog's model avoids copying gigabytes.

Lazyjournal is a TUI over journalctl. The difference is scope. Lazyjournal is about one machine's journal; Nerdlog is about many hosts at once, merges their responses into a unified view, and draws a histogram across the merged set. Nerdlog will use journalctl as a source, but only as a fallback, and the README explains that preference as a performance and reliability judgement.

Compared with Graylog or Kibana, the README's framing is that Nerdlog is loosely inspired by them but without the bloat and with pretty much no setup needed. The real difference is architectural: Graylog and Kibana require ingest, storage and an index before you can query anything. Nerdlog requires SSH and nothing else. The cost of that trade is retention, correlation across time beyond what you re-query, and any kind of shared access control.

Maintenance, build dependencies and licence

The repository is not archived, and the last push was on 2026-08-30. The most recent release listed is v1.10.0 from 2025-06-09, preceded by v1.9.0 on 2025-06-02 and v1.8.2 on 2025-05-25, so the release cadence in mid-2025 was tight and the repository has seen commits since the last tagged release.

Upgrade cost is low by construction. Nerdlog is a single Go binary with no server component and no database, so upgrading means replacing the binary. There is no schema migration, no index rebuild, and no agent to redeploy on the remote hosts, because the remote side is just the SSH session and the commands Nerdlog runs over it. The one thing to check on upgrade is the logstreams config file format, since ~/.config/nerdlog/logstreams.yaml is user-editable state that lives outside the binary.

Build dependencies are worth noting for packagers. go.mod pins Go 1.24 and pulls in tcell, tview, ssh_config, glob, go-runewidth, uniseg, pflag, yaml.v2 and golang.design/x/clipboard, among others. The clipboard library is the reason Linux builds need libx11-dev. The Makefile injects version, commit, date and builtBy via ldflags, so a build outside make will report different version metadata unless you replicate those flags.

The licence is BSD-2-Clause, a permissive licence. That permits use and redistribution with the copyright notice and disclaimer retained. It is not a copyleft licence, so it does not impose source-disclosure obligations on derivative works. This is a description of the licence text, not legal advice; check the LICENSE file in the repository for the exact terms before you rely on it.

Editorial conclusion

Adopt Nerdlog if you already have SSH access to the machines whose /var/log/messages, /var/log/syslog or journalctl output you read, and you want a histogram over a fleet without operating Elasticsearch or Graylog. Skip it if your logs only exist in a managed service, if your hosts are Windows, or if you need a shared, auditable query history that several people can revisit. Before rolling it out, verify that your logstreams resolve the way you expect by running nerdlog against one host and checking whether it picked the log file or journalctl, then confirm that the 250-message default window is enough for the queries you actually run.

Frequently asked questions

Official sources

1. dimonomid/nerdlog on GitHub
2. License: BSD-2-Clause
3. Project website
4. README
5. Releases