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 |
Ping task type auto — probes once and uses a protocol the target actually answers |
✅ available |
Ping task type dual — measures ICMP and TCP in the same cycle, so "target only answers TCP" reads as ICMP 100% / TCP 2ms instead of a flat 100% loss |
✅ available |
| Reference target on a ping task — probe your gateway alongside the target, to tell a local problem from an upstream one | ✅ available |
| Baseline alerting — alert on deviation from a rule's own P95 history instead of a hand-tuned absolute threshold | ✅ available |
Backup freshness metric (backup.age_seconds / backup.ok) — alert when backups stop, not only when a host goes down |
✅ available |
IP information API (/api/*/ip-info/v1) — geo, ASN, network type and Globalping latency, for themes that render an IP panel |
✅ available |
| Address-family aware scheduling — a node with no IPv4 address is skipped on IPv4-literal targets instead of reporting a permanent 100% loss, which is a structural mismatch rather than an outage | ✅ 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) |
✅ |
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
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.
Docker
docker run -d --name nekomari \
-p 25774:25774 \
-v nekomari-data:/app/data \
ghcr.io/aone2233/nekomari:latest
Multi-arch (linux/amd64, linux/arm64), anonymously pullable. The binary inside
is the same one attached to the release.
[!IMPORTANT] Always pass
-v. The image declaresVOLUME /app/data, so running it without one makes Docker create an anonymous volume. Updating the image means recreating the container, and the new container gets a different anonymous volume — so the panel starts with an empty data directory and shows the install wizard again. Your data is not deleted, just orphaned, but from the outside it looks exactly like "the update reset my settings".Either a named volume (
-v nekomari-data:/app/data, above) or a bind mount (-v /opt/nekomari/data:/app/data) is fine. The server logs a warning at startup if it detects the anonymous case.
With Compose:
services:
nekomari:
image: ghcr.io/aone2233/nekomari:latest
restart: unless-stopped
ports:
- "127.0.0.1:25774:25774" # keep it on loopback; put a reverse proxy in front
volumes:
- ./data:/app/data
environment:
TZ: Asia/Shanghai
Agents hold long-lived WebSocket connections, so a reverse proxy in front must pass the upgrade headers — see deploy/nginx-nekomari.conf.
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). The upstream
installation guide describes the
base software's Docker and deployment options; it documents Komari, so where the
two differ, this repository's docs/ wins.
To connect a node, download the agent from
Releases and point it at the
panel — deploy/install-node-agent.sh does it for a Linux host, including the
checksum check and the systemd unit.
Documentation
| Document | Contents |
|---|---|
| FORK.md | Provenance, base commit, and the full change list |
| CHANGELOG.md | What changed in each release, and why |
| CONTRIBUTING.md | How to build, test and submit a change |
| docs/SILENT-FAILURES.md | Where the system knows something is wrong and does not say so |
| docs/OPEN-WORK.md | What is unfinished, what is blocked, and what will bite again |
| docs/RELEASING.md | How to cut a release, and the two traps |
| docs/TESTING.md | Which tests are hermetic; which need root or IPv6 |
| docs/DEPLOY-OC424.md | The public deployment: topology, data restore, node reconnection |
| docs/RETIRE-CF-PROBE.md | Retiring the previous monitoring stack, and how to roll it back |
| docs/SECRETS.md | The no-credentials rule, and the token-leak incident record |
| docs/API-KEYS.md | Scoped-key lifecycle, exact permissions, legacy consumer migration and rollback gates |
| docs/HERMES-NODE-CLIENT.md | Metadata-only Hermes CLI, hidden owner-TTY key handoff and remaining live transition steps |
| docs/CLIENT-TOKEN-ROTATION.md | Session-only Agent-token rotation, retirement boundaries, independent recovery and compatibility gates |
| docs/V1.7-CUTOVER-READINESS.md | Delivered v1.7 cutover evidence, historical conditions and remaining owner acceptance/handoff |
| docs/ENCRYPTED-BACKUPS.md | Recipient-only tooling, encrypted nightly schedule and isolated restore contract |
| docs/MAC-WAN-RECOVERY.md | Online key custody, actual pre/post encrypted recovery and owner-reported offline copy |
| docs/DEPLOY-VERIFICATION.md | Deploy verification on a test host, and what it found |
| docs/IP-INFO-API.md | The /api/*/ip-info/v1 contract, its upstreams, and caching |
| deploy/README.md | What each operational script does, and why some hosts need their own |
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
|
|
|
unlock
Package unlock 保存与读取节点的「流媒体 / AI 解锁」探测结果。
|
Package unlock 保存与读取节点的「流媒体 / AI 解锁」探测结果。 |
|
deploy
|
|
|
experiments
command
Minimal raw-ICMP socket probe, built and run with the same file capability as the agent.
|
Minimal raw-ICMP socket probe, built and run with the same file capability as the agent. |
|
internal
|
|
|
apikeys
Package apikeys implements scoped, expiring, non-recoverable credentials.
|
Package apikeys implements scoped, expiring, non-recoverable credentials. |
|
bulk
Package bulk applies one change to many nodes, one at a time, and reports each outcome.
|
Package bulk applies one change to many nodes, one at a time, and reports each outcome. |
|
clientguard
Package clientguard orders short agent operations and credential retirement per node.
|
Package clientguard orders short agent operations and credential retirement per node. |
|
configxport
Package configxport turns the panel's configuration into one JSON document and applies one back.
|
Package configxport turns the panel's configuration into one JSON document and applies one back. |
|
cycle
Package cycle computes the billing cycle a node's traffic belongs to.
|
Package cycle computes the billing cycle a node's traffic belongs to. |
|
dbcache
Package dbcache tracks writes to small configuration tables.
|
Package dbcache tracks writes to small configuration tables. |
|
forecast
Package forecast projects a node's traffic for the rest of its billing cycle, and says when it would reach its plan limit.
|
Package forecast projects a node's traffic for the rest of its billing cycle, and says when it would reach its plan limit. |
|
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. |
|
maintenance
Package maintenance decides whether a node is inside a maintenance window, and what to do with a notification that arrives while it is.
|
Package maintenance decides whether a node is inside a maintenance window, and what to do with a notification that arrives while it is. |
|
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. |
|
sla
Package sla computes availability, latency percentiles and outage intervals from the metrics the panel already stores.
|
Package sla computes availability, latency percentiles and outage intervals from the metrics the panel already stores. |
|
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 探测一个目标的可达性与「协议适配」。 |
|
secretcmp
Package secretcmp 比较密钥而不泄露比较耗时。
|
Package secretcmp 比较密钥而不泄露比较耗时。 |
|
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. |
|
notifier
Package maintenance windows, for the notifier: it answers "should this alert be sent now, and if not, when" using the rules in internal/maintenance.
|
Package maintenance windows, for the notifier: it answers "should this alert be sent now, and if not, when" using the rules in internal/maintenance. |
|
web
|
|
|
api/ipinfo
Package ipinfo 实现第三方主题（LuminaPlus）所需的「IP 信息」HTTP 接口。
|
Package ipinfo 实现第三方主题（LuminaPlus）所需的「IP 信息」HTTP 接口。 |
|
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. |