README
ยถ
Nekomari
๐ฑ Nekomari is a fork of Komari
Base version:
1.5.0-fix1(commit0ca87aa, 2026-09-14) โ the last release published before upstream was archived. Upstream is archived and no longer maintained; Nekomari continues it with new features. See FORK.md for full provenance and the change list.Licensed MIT, same as upstream. The original copyright (c) 2025 Komari Moniter is preserved verbatim in
LICENSEandNOTICE.
Nekomari is a lightweight, self-hosted server monitoring solution โ a maintained continuation of Komari. It provides a simple and efficient way to track server performance through a web interface, with metrics collected by a lightweight agent.
[!WARNING] Nekomari is a self-hosted monitoring and control application. Deploy it only on systems you own or are authorized to manage. You are solely responsible for how you deploy and use it. The developers accept no liability for unauthorized access, persistence, command execution, other misuse, or any resulting consequences.
What Nekomari adds over upstream
| Change | Status |
|---|---|
netcheck โ multi-protocol reachability probe (DNS + ICMP + TCP) that tells you which probe type a target actually supports |
โ available |
Monorepo layout โ server + frontend/ + agent/ in one repository |
โ |
Bundled theme packer (tools/zstdpack) โ builds without the zstd CLI (useful on Windows) |
โ |
One-shot build script (build.sh) |
โ |
| Further features in progress | ๐ง see FORK.md |
netcheck in 20 seconds
Monitoring tasks probe a target with one protocol (ICMP, TCP or HTTP). Pick the wrong one and you get a flat 100% packet loss โ which looks like an outage but is really a protocol mismatch. netcheck tells you up front which one to use:
$ ./nekomari netcheck 1.51.3.134
ICMP probe (3x, timeout 3s)
x recv 0/3 loss 100% -- target does not answer ICMP
TCP probe (timeout 3s)
x 22 unreachable
v 80 open (handshake 2 ms)
v 443 open (handshake 2 ms)
----------------------------------------------------------
Verdict: TCP-only reachable (does not answer ICMP)
Advice: this target does NOT answer ICMP, but TCP:80,443 is open. Use a `tcp`
probe task and write the target as host:port (e.g. 1.51.3.134:80),
otherwise you will get 100% packet loss.
It also distinguishes "permission denied" from "target unreachable" โ otherwise a non-privileged ICMP attempt leads to the opposite conclusion.
Features
- Real-time monitoring: Displays monitoring data at one-second intervals.
- Lightweight and efficient: Uses minimal system resources and works well on servers of any size.
- Self-hosted: Keeps you in control of your data and privacy.
- Web interface: Provides an intuitive, easy-to-use monitoring dashboard.
Features
These describe the base software Nekomari inherits from Komari:
- Real-time monitoring โ data at one-second intervals.
- Lightweight โ minimal system resources; runs on small servers.
- Self-hosted โ your data stays on your machines.
- Web interface โ a dashboard for both the public view and administration.
- Extensible โ custom themes and plugins.
Quick start
Prebuilt binaries
Download from Releases. Each
release ships the server and the agent for linux/amd64, linux/arm64 and
windows/amd64, plus SHA256SUMS.txt.
./nekomari-linux-amd64 server # open http://localhost:25774 to install
./komari-agent-linux-amd64 -e https://your-panel -t <token>
The agent binary keeps the komari-agent- prefix because that is the filename
its self-updater looks for โ see docs/RELEASING.md.
Build from source
Requires Go (see go.mod), Node 22+, and a C toolchain โ the server links
SQLite through CGO, so CGO_ENABLED=0 will not build it.
./build.sh # frontend -> embedded theme -> server -> agent
build.sh runs all five steps including the theme packer, so it needs no
external zstd binary.
Installation notes
The installer asks for a metric store DSN (SQLite by default). See the
installation guide for the
base software's Docker and deployment options โ that documentation describes
Komari, which Nekomari is built on; where the two differ, this repository's
docs/ wins.
Documentation
| Document | Contents |
|---|---|
| FORK.md | Provenance, base commit, and the full change list |
| docs/RELEASING.md | How to cut a release, and the two traps |
| docs/TESTING.md | Which tests are hermetic; which need root or IPv6 |
Credits and provenance
Nekomari is a fork of Komari,
based on 1.5.0-fix1 (commit 0ca87aa). Upstream is archived, and this project
continues it.
Thanks are due to everyone who contributed to Komari โ see the upstream contributors. None of them are responsible for anything added here.
Sponsors and donations: this fork has none. The sponsorship and donation sections you may remember from upstream's README belonged to the upstream maintainer and were deliberately removed here, so that nothing in this repository implies an endorsement or a payment channel that does not exist. If you want to support the original author, do it through the upstream repository.
License
MIT, unchanged. The original copyright notice is preserved verbatim in LICENSE and NOTICE.
Documentation
ยถ
There is no documentation for this package.
Source Files
Directories
ยถ
| Path | Synopsis |
|---|---|
|
agent
module
|
|
|
internal
|
|
|
lifecycle
Package lifecycle carries process-level requests without coupling web RPC handlers to the server runtime.
|
Package lifecycle carries process-level requests without coupling web RPC handlers to the server runtime. |
|
managedconfig
Package managedconfig implements the shared managed-configuration behavior used by themes and plugins.
|
Package managedconfig implements the shared managed-configuration behavior used by themes and plugins. |
|
plugin
Package plugin manages Komari plugins: ZIP packages with a komari-plugin.json manifest, mirroring the theme package format.
|
Package plugin manages Komari plugins: ZIP packages with a komari-plugin.json manifest, mirroring the theme package format. |
|
sqlitetune
Package sqlitetune applies a consistent SQLite baseline to every physical connection opened through database/sql.
|
Package sqlitetune applies a consistent SQLite baseline to every physical connection opened through database/sql. |
|
pkg
|
|
|
jsruntime
Package jsruntime host services for modules injected by the application.
|
Package jsruntime host services for modules injected by the application. |
|
jsruntime/crypto
Package crypto provides a Node.js-compatible crypto module backed by the Go standard library and golang.org/x/crypto.
|
Package crypto provides a Node.js-compatible crypto module backed by the Go standard library and golang.org/x/crypto. |
|
jsruntime/httpbody
Package httpbody provides bounded helpers for reading HTTP request or response bodies.
|
Package httpbody provides bounded helpers for reading HTTP request or response bodies. |
|
jsruntime/internal/bridge
Package bridge provides the small set of runtime services shared by host modules.
|
Package bridge provides the small set of runtime services shared by host modules. |
|
netcheck
Package netcheck ๆขๆตไธไธช็ฎๆ ็ๅฏ่พพๆงไธใๅ่ฎฎ้้
ใใ
|
Package netcheck ๆขๆตไธไธช็ฎๆ ็ๅฏ่พพๆงไธใๅ่ฎฎ้้ ใใ |
|
protocol
|
|
|
log
Package logger provides the server's single runtime logging surface.
|
Package logger provides the server's single runtime logging surface. |
|
messageSender/outboundhttp
Package outboundhttp provides the HTTP client used by configurable notification senders.
|
Package outboundhttp provides the HTTP client used by configurable notification senders. |
|
web
|
|
|
backup
Package backup contains the shared upload preparation for backup restores.
|
Package backup contains the shared upload preparation for backup restores. |
|
filemanager
Package filemanager correlates panel file requests with agent responses.
|
Package filemanager correlates panel file requests with agent responses. |
|
migration
Package migration serves the authenticated database migration guide used by both legacy monitoring imports and Metric Store structure upgrades.
|
Package migration serves the authenticated database migration guide used by both legacy monitoring imports and Metric Store structure upgrades. |
|
recovery
Package recovery serves the small, authenticated web surface used when the monitoring database cannot be opened during startup.
|
Package recovery serves the small, authenticated web surface used when the monitoring database cannot be opened during startup. |
|
upload
Package upload provides the shared chunked archive upload flow.
|
Package upload provides the shared chunked archive upload flow. |