Komari: a self-hosted server monitor with a web terminal and a plugin layer

What Komari is for, and who ends up running it

Komari is a self-hosted server monitoring application. The README describes it as a lightweight way to track server performance through a web interface, with metrics collected by a lightweight agent. The repository topics list monitoring, monitoring-tool and remote-control, which is a more honest summary than the feature list: this is not a passive dashboard, it is a control surface.

The intended user is someone who owns the machines being watched. The README carries an explicit warning that Komari is a self-hosted monitoring and control application and should be deployed only on systems you own or are authorized to manage, and that the developers accept no liability for unauthorized access, persistence, command execution or other misuse. That warning is not boilerplate. The feature list includes a web terminal and remote control, so a Komari instance that is reachable by the wrong person is a foothold, not a graph.

The project is written in Go and licensed MIT, with a NOTICE file alongside the LICENSE at the repository root. The module path is github.com/komari-monitor/komari and go.mod declares go 1.25.0, so building from source requires a recent Go toolchain. The last push to the default branch was on 2026-09-22, and the most recent release is tagged Snapshot-2609221516 from the same day, following 1.5.0 and 1.5.0-fix1 on 2026-09-14.

The agent, the server and the plugin runtime

The repository layout separates the pieces. main.go sits at the root, cmd/ holds the command entry points (the Dockerfile invokes the binary with the server subcommand, so command dispatch is part of the design), internal/ and pkg/ hold the application code, protocol/ holds the agent-to-server wire format, database/ holds persistence, utils/ holds helpers, and web/ holds the frontend assets that the Go server serves.

go.mod tells you more about the runtime than the README does. gin-gonic/gin provides the HTTP layer, gorilla/websocket handles the streaming path that a one-second refresh rate implies, gorm with the sqlite driver is the default persistence story, and the mysql and pgx/v5 drivers are present as alternatives. klauspost/compress is a dependency, which suggests payloads are compressed on the wire. maxminddb-golang is there for IP geolocation. pquerna/otp means two-factor authentication is implemented, and dop251/goja plus goja_nodejs means the extensibility the README mentions is a JavaScript runtime embedded in the Go process, not a compiled plugin ABI.

That last point matters more than any other line in go.mod. Custom themes and plugins are executed through goja, so a plugin is JavaScript evaluated inside the server. The README does not document the plugin sandbox or what a plugin can reach, and it does not describe how plugin code is distributed or signed. If you plan to install third-party plugins, treat that as an open question you must answer from the documentation and the source, not from the feature list.

Installing Komari and getting the first agent connected

The README does not inline installation steps. It states that for Docker deployment, binary installation, building from source and updates, you should see the installation guide at komari.wiki. There is also an install-komari.sh script at the repository root, and two one-click deployment listings: a Rainyun app store entry and a 1Panel app store entry. The official documentation site is linked as https://www.komari.wiki/.

What the repository does give you is the container contract. The Dockerfile builds from alpine:3.21, copies the prebuilt binary named komari-${TARGETOS}-${TARGETARCH} into /app/komari, sets GIN_MODE=release, sets KOMARI_LISTEN to 0.0.0.0:25774, sets GODEBUG=disablethp=1, exposes port 25774, and runs the binary with the server argument.

ENV GIN_MODE=release
ENV KOMARI_LISTEN=0.0.0.0:25774
ENV GODEBUG=disablethp=1
EXPOSE 25774
CMD ["/app/komari", "server"]

Those four lines are the whole operational surface the repository hands you. KOMARI_LISTEN controls the bind address, so if you want the dashboard on loopback behind a reverse proxy you override it rather than editing the image. The Dockerfile does not declare a VOLUME or name a data directory, and the README does not document where the SQLite file is written, so confirm the persistence path from the install guide before you map a volume. After the container starts, the dashboard is served on port 25774 and the first run is where you create the admin account and enroll agents. The README does not document the enrollment flow, the agent package name or the agent's configuration file, so read the quick-start page before pointing the agent at production hosts.

Where Komari is the wrong tool

The one-second interval is the sharpest constraint. The README lists real-time monitoring at one-second intervals as the first feature, and the websocket dependency in go.mod is consistent with pushing those samples to the browser. One-second sampling multiplies your storage and write load by sixty compared with a one-minute scrape, and it produces a time series that is mostly noise for capacity planning. If your question is whether a disk will fill in three weeks, Komari's resolution is far finer than you need and the retention cost is real. The README does not document retention policies or downsampling, so you cannot assume either exists.

The remote-control surface is the second constraint. A monitoring tool that can open a web terminal on the watched host is a different risk class from one that only reads metrics. The README's own warning names unauthorized access, persistence and command execution as the failure modes. If your environment requires that the observability path be strictly read-only, Komari's design is pointed the other way.

The third constraint is documentation depth. Installation, agent setup, plugin authoring and update procedures all live on komari.wiki, and the README does not reproduce them. That is a normal choice for a project with a documentation site, but it means the repository alone is not enough to evaluate operational fit. The README also does not document rollback, backup or restore, and it does not state an upgrade compatibility policy.

Komari compared with Prometheus and node_exporter

The obvious comparison is Prometheus with node_exporter. The difference is architectural, not cosmetic. Prometheus pulls: it scrapes an HTTP endpoint on each target on its own schedule, stores samples in its own time-series database, and the exporter is a passive process with no channel back to the server. Komari pushes, or at least streams: an agent reports to a server, and the server holds a websocket path to the browser. The agent is a participant in a session, which is exactly what makes the web terminal possible.

That inversion has consequences. With Prometheus, compromising the server does not give you a shell on the targets, because the scrape endpoint only answers reads. With Komari, the control channel is the same channel that carries metrics, and the README's warning is written accordingly. On the other side, Prometheus requires you to run and size a TSDB and to think about scrape intervals, retention and recording rules; Komari ships as one binary with SQLite by default, which is a much smaller operational footprint for a handful of machines.

PromQL is the other dividing line. Prometheus gives you an expression language for aggregation and alerting across many targets. The README describes Komari's interface as a dashboard with history charts and themes; it does not describe a query language or an alerting rule engine. If you need to express conditions like a rolling error budget across a fleet, Prometheus answers that question and Komari, on the evidence of the README, does not.

Maintenance, upgrades and what the MIT licence leaves to you

The release cadence is fast. 1.5.0 and 1.5.0-fix1 landed on 2026-09-14, and a snapshot build tagged Snapshot-2609221516 landed on 2026-09-22, the same day as the last push to main. Snapshot tags in a release list usually mean the project publishes builds from the default branch between numbered versions. If you deploy snapshots, you are tracking main and you should expect the surface to move; the README does not state a support window for older releases, and it does not document a downgrade path.

For upgrades, the install guide is the only stated source, and the README explicitly routes updates there. Nothing in the repository describes database migrations, so if you run Komari against MySQL or PostgreSQL rather than SQLite, verify the migration behaviour before an upgrade rather than after.

The MIT licence is permissive: it allows use, modification and redistribution with the copyright notice and permission notice retained. The repository also carries a NOTICE file, which is worth reading because it can record attributions or additional terms that the LICENSE file alone does not cover. This is not legal advice; if you redistribute Komari inside a product, have someone check the LICENSE and NOTICE together. Separately, the README's liability disclaimer about unauthorized access and command execution is a statement about the developers' position, not a shield for your deployment. Whoever runs the instance carries the operational and legal exposure for what it can reach.

Editorial conclusion

Adopt Komari if you already run your own infrastructure and want a single Go binary plus a web UI you control, and if you accept that the install instructions live at komari.wiki rather than in the repository. Skip it if you need an audited, agentless or long-term-support monitoring stack, or if you cannot justify giving a web application remote control over the hosts it watches. Before deploying, read the install guide end to end, confirm which database driver you will use among the SQLite, MySQL and PostgreSQL options in go.mod, and check that the 25774 listener is reachable only from the networks you intend.

Frequently asked questions

Official sources

1. komari-monitor/komari on GitHub
2. License: MIT
3. Project website
4. README
5. Releases