Nezha Monitoring: a self-hosted dashboard and agent for servers and websites
:trollface: Self-hosted, lightweight server and website monitoring and O&M tool
At a glance
- What is it?
- Nezha Monitoring is a Go dashboard plus a per-server agent that reports system status, HTTP, TCP and Ping results, and also runs scheduled tasks and a web terminal. It suits operators of a handful of VPSes more than large fleets, and the README's install path is a documentation link rather than a copy-paste script.
- Who is it for?
- Adopt Nezha Monitoring if you run a small set of VPSes or websites and want one self-hosted place for status, alerts, scheduled tasks and a web terminal, and you are willing to follow the official docs at nezhahq.github.io because the README itself does not carry install steps. Skip it if you need a long retention window for high-cardinality metrics, or if you cannot accept that the dashboard holds SSH-equivalent access to every agent.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 11 days ago.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 25, 2026, and from our analysis. They are not legal advice.
Editorial analysis
The gap Nezha Monitoring fills between uptime pings and a full metrics stack
Most small operators end up with two tools: an external uptime checker for HTTP endpoints and something heavier for CPU, memory and disk on each box. Nezha Monitoring targets the middle. The README describes it as a "Self-hostable, lightweight, servers and websites monitoring and O&M tool" and lists what it covers: system status, HTTP checks including SSL certificate change, upcoming expiration and expired states, TCP, Ping, push alerts, scheduled tasks and a web terminal. The O&M part is the differentiator. Alerts tell you a disk filled up; a scheduled task or a web terminal lets you do something about it from the same UI. The audience is the person who owns five to fifty VPSes, wants the data on their own hardware, and does not want to run Prometheus, Alertmanager and Grafana as three separate services. If your fleet is large enough to need long-term metric storage with high cardinality, this is the wrong shape of tool, and that is a design choice rather than a defect.
Dashboard, agent and the gRPC channel between them
The repository splits into a dashboard and an agent. The dashboard is the Go server in cmd/ and service/, built on gin for HTTP and gin-jwt for authentication, with SQLite as the default store (gorm.io/driver/sqlite and mattn/go-sqlite3 in go.mod) and VictoriaMetrics as a metrics dependency. Agents connect back to the dashboard over gRPC (google.golang.org/grpc and google.golang.org/protobuf are both direct requirements), which is how status flows in and commands flow out. That bidirectional channel is what makes the web terminal and scheduled tasks possible: the dashboard is not just receiving samples, it can push work down to an agent that is already connected. The proto/ directory holds the contract between the two sides, and integration/ suggests there is test coverage across that boundary. A few dependencies hint at features the README does not spell out: libdns with Cloudflare, HE and Tencent Cloud providers points at DNS record management, maxminddb-golang points at IP geolocation, and modelcontextprotocol/go-sdk is present in the module graph. The README does not document what those are used for, so treat them as things to confirm in the docs rather than features.
Installing Nezha Monitoring and getting the first agent to report
The README does not contain install commands. It points at the user guide, with an English edition at https://nezhahq.github.io/en_US/index.html and a Chinese edition at https://nezhahq.github.io/index.html, so the exact deployment steps live there and should be followed from that source. What the repository does pin down is the container contract. The Dockerfile builds a runtime image on busybox:stable-musl, copies the compiled dashboard binary into /dashboard/app, declares /dashboard/data as a volume for the SQLite database and related state, exposes port 8008, and defaults the timezone to Asia/Shanghai through the TZ build argument and environment variable. The entrypoint is script/entrypoint.sh. So the shape of a deployment is a single container with one persistent volume and one exposed port, regardless of which install method the docs recommend.
FROM alpine AS depend
RUN apk add --update --no-cache ca-certificates tzdata
FROM busybox:stable-musl
COPY ./script/entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh
WORKDIR /dashboard
COPY dist/dashboard-${TARGETOS}-${TARGETARCH} ./app
VOLUME ["/dashboard/data"]
EXPOSE 8008
ARG TZ=Asia/Shanghai
ENV TZ=$TZ
ENTRYPOINT ["/entrypoint.sh"]That is the repository's own Dockerfile, reproduced to show what a container built from it expects. The volume line is the one that matters operationally: if /dashboard/data is not backed by durable storage, the dashboard comes back empty after a container replacement. The TZ variable is a build argument with a default, so an image built without overriding it will report times in Asia/Shanghai.
For the agent side, the README badges link to a separate repository, nezhahq/agent, which carries its own release stream and CI workflow. That means dashboard and agent are versioned independently, and the docs are the place to check which agent release pairs with which dashboard release. The README gives no install command for the agent, so the honest first step is to open the English guide, follow its dashboard install, then follow its agent install and confirm the server appears with a status line in the dashboard. Until that happens, nothing else in the product is reachable. The Dockerfile's EXPOSE 8008 and VOLUME ["/dashboard/data"] lines are the two facts to carry into whatever run command the guide gives you: publish that port, and mount that path.
Where Nezha Monitoring is the wrong tool
The web terminal is the sharpest trade-off in the product. To offer a terminal from the dashboard, the agent has to accept commands from the server, which means whoever holds dashboard admin credentials effectively holds shell access to every connected machine. That is a large blast radius for a monitoring tool, and it is the reason a team with strict separation between monitoring and access should think twice, or at least scope the dashboard's exposure carefully. The README does not document a per-agent permission model for the terminal, so do not assume one.
Retention is the second limit. SQLite is the default store and VictoriaMetrics is a dependency, but the README says nothing about how long samples are kept or how the two stores divide the work. Anyone who needs months of high-resolution history for capacity planning should confirm that in the docs before committing, because a lightweight self-hosted tool is usually optimized for recent state rather than long-range analysis.
Upgrades are the third. The dashboard and the agent are separate repositories with separate release cadences and a gRPC contract between them defined in proto/. A dashboard upgrade that changes that contract can leave older agents unable to connect. The README does not document a rollback procedure, and it does not state a compatibility policy between dashboard and agent versions. Plan to read the release notes for both sides, and keep the /dashboard/data volume backed up before an upgrade so a bad pairing can be reversed.
Nezha Monitoring compared with Prometheus and Grafana
The obvious alternative for the same job is Prometheus with node_exporter and Grafana. The difference is not features, it is direction and shape. Prometheus pulls: it scrapes an HTTP endpoint on each target on a schedule, so the target does not need an outbound connection or a persistent session. Nezha's agents connect to the dashboard over gRPC, which means the dashboard can push commands back down the same channel. That is precisely why Nezha has a web terminal and scheduled tasks and a stock Prometheus setup does not: a pull-based scraper has no channel for commands.
The cost is operational. Prometheus gives you a query language, long retention via its own storage, and a mature alerting rule format; Nezha gives you a dashboard, alerts, tasks and a terminal in one binary with SQLite behind it. If your questions are of the form "what was p99 latency three months ago", Prometheus answers them and Nezha probably will not. If your questions are "is this box up, is the certificate about to expire, and can I restart the service from here", Nezha answers them with far less to run. The two are not mutually exclusive, but running both means maintaining two alert paths, and that is a real cost.
Licence, releases and what an upgrade actually costs
Nezha Monitoring is Apache-2.0, which permits commercial use, modification and redistribution provided the licence and notices are preserved and any modified files are marked. It also includes an explicit patent grant. The repository contains a LICENSE file at the top level, and that file is the authority, not this summary. If you plan to redistribute a modified dashboard, read the LICENSE and NOTICE requirements yourself; this is a description of the licence, not legal advice.
The maintenance signal is strong. The last push to master was on 2026-09-19, and releases v2.3.11, v2.3.12 and v2.3.13 landed on 2026-09-13, 2026-09-14 and 2026-09-19 respectively. That is a tight release cadence, and it means an operator should expect to move reasonably often rather than sit on one version for a year. The upgrade cost is not the dashboard alone. Because the agent lives in nezhahq/agent and speaks gRPC to the dashboard, a dashboard bump can require an agent bump, and the agent is deployed on every monitored machine. Multiply the per-host upgrade by your fleet size before deciding how eagerly to track releases. There is a SECURITY.md in the repository, which is where the maintainers describe how to report a vulnerability; read it before you need it.
Editorial conclusion
Adopt Nezha Monitoring if you run a small set of VPSes or websites and want one self-hosted place for status, alerts, scheduled tasks and a web terminal, and you are willing to follow the official docs at nezhahq.github.io because the README itself does not carry install steps. Skip it if you need a long retention window for high-cardinality metrics, or if you cannot accept that the dashboard holds SSH-equivalent access to every agent. Before rolling it out, verify the dashboard version against the agent version, confirm the data volume is backed up, and check the SECURITY.md file for how the maintainers want vulnerabilities reported.
Frequently asked questions
Is Nezha Monitoring free to self-host?
Yes. The repository is licensed under Apache-2.0, which permits self-hosting, modification and redistribution under the terms in the LICENSE file. There is no separate paid tier described in the README.
What can Nezha Monitoring check?
The README lists system status, HTTP checks (including SSL certificate change, upcoming expiration and expired), TCP and Ping. It also supports push alerts, scheduled tasks and a web terminal.
Which port does the Nezha Monitoring dashboard use?
The repository's Dockerfile exposes port 8008 and sets the working directory to /dashboard, with /dashboard/data declared as a volume. The README itself does not restate the port.
Does Nezha Monitoring store its data in a database?
The go.mod file lists gorm.io/driver/sqlite and github.com/mattn/go-sqlite3 as direct dependencies, and the Dockerfile declares /dashboard/data as a volume, which is where that state would live. The README does not describe the schema or retention.
Where are the Nezha Monitoring installation instructions?
The README links to the user guide at https://nezhahq.github.io/en_US/index.html for English and https://nezhahq.github.io/index.html for Chinese. It does not include install commands itself.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/nezhahq-nezha)