nitr

KO | EN

gitlite — search

#javascript #hacktoberfest #react #typescript #llm #go #machine-learning #rust #linux #docker #java #awesome #cli #pytorch

(★ 52)

:computer: Nitr is a System and Hardware Inspection and Monitoring Web API.

nitr 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

![Go version](https://raw.githubusercontent.com/bitcav/nitr/master/images/goversion.svg) [![CI](https://github.com/bitcav/nitr/actions/workflows/ci.yml/badge.svg)](https://github.com/bitcav/nitr/actions/workflows/ci.yml) ![Release](https://raw.githubusercontent.com/bitcav/nitr/master/images/release.svg) ![Go report](https://raw.githubusercontent.com/bitcav/nitr/master/images/goreport.svg) [![MIT license](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/bitcav/nitr/blob/master/LICENSE) ![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20Windows-blue.svg)

</div>

# Nitr

A **cross-platform remote monitoring tool** written in Go that exposes **system and hardware information** (CPU, RAM, disks, network, processes, and more) through a **JSON API**, so it can be consumed by web admin panels, mobile apps, or anything that speaks HTTP.

> CLI demo — basic system info, no API key required

**Quick start:**

```bash
# Linux — detects your arch, downloads, chmods, verifies the binary runs
curl -fsSL https://raw.githubusercontent.com/bitcav/nitr/master/install.sh | bash
```

The installer downloads into the **current directory** — nothing is placed on your PATH. Run it as `./nitr` from here, or make it available globally with `sudo mv nitr /usr/local/bin/nitr`.

```bash
./nitr          # starts the server in the foreground (default port 8000)
                # and creates nitr.db + config.ini in this directory
```

`./nitr` blocks here — the server is running. The commands below need `nitr.db`, so they only work once the server has run in this directory. Run them in a **second terminal in the same directory**, or after stopping the server with `Ctrl+C`:

```bash
./nitr passwd   # change the default password before going further
./nitr key      # print your API key (prompts for the password)
```

See [Usage](#usage) for how to call the API with that key.

## Table of contents

- [Installation](#installation)
  - [Quick install](#quick-install)
  - [Download](#download)
  - [Build](#build)
- [Running](#running)
- [Commands](#commands)
- [Docker](#docker)
- [Web panel](#web-panel)
- [QR Code](#qr-code)
- [Usage](#usage)
  - [Example](#example)
- [HTTP behaviour](#http-behaviour)
- [Prometheus metrics](#prometheus-metrics)
- [Health and readiness probes](#health-and-readiness-probes)
- [API v1](#api-v1)
  - [Available endpoints](#available-endpoints)
  - [Time-range queries](#time-range-queries)
  - [JSON data references](#json-data-references)
- [Settings](#settings)
- [Platform support](#platform-support)
- [Powered by](#powered-by)

## Installation

### Quick install

**Linux (amd64/386/arm64)** — get the binary via the [`install.sh`](install.sh) one-liner from the top of this README, or fetch it directly:
```
curl -L https://github.com/bitcav/nitr/releases/latest/download/nitr_linux_amd64 -o nitr
chmod +x nitr
```

**Windows (amd64) — PowerShell**
```
Invoke-WebRequest https://github.com/bitcav/nitr/releases/latest/download/nitr_windows_amd64.exe -OutFile nitr.exe
```

> On 32-bit systems, swap the asset name for `nitr_linux_386` or `nitr_windows_386.exe`.

### Download

https://github.com/bitcav/nitr/releases/latest

### Build

Note: go version 1.26 or higher is required building it from the source.

#### Clone
```
git clone https://github.com/bitcav/nitr.git
```
#### Build
```
cd nitr
go build
```

## Running

**Linux**
```
./nitr
```

**Windows**
You can double click the .exe file or type in cmd
```
nitr.exe
```
the server will start listening on port 8000 by default

It writes `nitr.db` and `config.ini` to the current working directory — always start it from the same directory you own.
A few endpoints require root on Linux: `/memory` outright, the `serial` field on `/chassis` and `/baseboard`, and the `serial`/`uuid` fields on `/product`. Without it they return `unknown` fields (`403` for `/memory`). Full per-endpoint privilege notes are in [`docs/openapi.json`](docs/openapi.json) (or rendered at `/docs` in the panel) — see [JSON data references](#json-data-references).

Both spellings — bare `nitr` and the explicit `nitr server` — start the server. Bare `nitr` is **not** deprecated: the Dockerfile's `CMD` and the Windows double-click flow above rely on it, and it stays the zero-argument default. `nitr server` is the self-documenting form (it is what `nitr --help` lists, what the installed system service's `ExecStart` invokes, and what reads clearly in a process list) and accepts the same persistent flags as the root command, e.g. `nitr server --port 9000`.

## Commands

Help:

```
nitr -h
```

Print the version:

```
nitr version
```

Change password:

```
nitr passwd
```

Get API key:

```
nitr key
```

Print QR code:

```
nitr qr
```

> `nitr passwd`, `nitr key`, and `nitr qr` operate on the database in the **current working directory** and need the server to have been started there first — running the server is the only thing that creates `nitr.db`. Without it they refuse and exit 1, creating nothing:
> ```
> Error: no nitr database found at /path/to/nitr.db — start the nitr server there first
> ```

## Docker

Build image using command:
```
docker build -t nitr . 
```

Run container:
```
docker run -d -p 8000:8000 nitr:latest
```

The image ships a `HEALTHCHECK` (30s interval, 5s timeout, 10s start period, 3 retries) that runs `wget -q -O /dev/null http://localhost:8000/health`, so `docker ps` reports a health status for the container alongside its uptime. `/health` needs no API key and no login, so the probe works out of the box. The health-status lifecycle is Docker's general `HEALTHCHECK` behaviour and was not separately observed for this image in the run that added it.

## Web panel

Go to [http://localhost:8000](http://localhost:8000) in your web browser

![preview](https://raw.githubusercontent.com/bitcav/nitr/master/images/login-web.png)

Access with default **password**: **123456**

![preview](https://raw.githubusercontent.com/bitcav/nitr/master/images/panel-metrics-web.png)

> Metrics tab — live CPU, RAM and disk usage (dark theme)

![preview](https://raw.githubusercontent.com/bitcav/nitr/master/images/panel-web.png)

> Overview tab — host info, API key and QR code

The panel is organised into two tabs — **Overview** (host info, API key, QR code) and **Metrics** — and supports a **dark/light theme** that follows the OS `prefers-color-scheme` by default with a manual toggle in the header; the choice is stored in the browser's `localStorage` and overrides the OS setting in both directions.

The **Metrics** tab shows live CPU and RAM usage as both numeric widgets and scrolling line charts (driven by the existing `/status` WebSocket stream). The charts hold **session-only history in the browser — roughly the last six minutes (120 samples at the default 3s push), with nothing persisted server-side**, so they start empty on every page load. Server-side retention is now available as an opt-in feature — see [Metric History Retention](#metric-history-retention) — but the panel charts do not consume it.

The layout reflows to a single column on small screens, and pinch-zoom works on mobile clients. The chart library (uPlot) is vendored into the binary — no CDN is used and no build step is required, so the panel keeps working on an air-gapped host.

## QR Code

The QR Code contains the exact same information displayed in the Host Info Panel formatted as JSON.

## Usage

Request system info with an HTTP `GET` to [one of the API endpoints](#available-endpoints), passing the `x-api-key` header with your ***API key*** as the value, and you will get a success response.

### Example

Requesting CPU information.

> With curl.
```
curl -X GET 'http://localhost:8000/api/v1/cpu' -H 'x-api-key:yourapikeyhere'
```
> With PowerShell.
```
Invoke-RestMethod -Uri http://localhost:8000/api/v1/cpu -H @{"x-api-key"="yourapikeyhere"}
```
> JSON response:

```json
{
	"vendor":"GenuineIntel",
	"model":"Intel(R) Core(TM) i7-4810MQ CPU @ 2.80GHz",
	"cores":4,
	"threads":8,
	"clockSpeed":3800,
	"usage":8.354430379674321,
	"usageEach":[
				9.803921568623954,
				7.692307692348055,
				4.166666666635087,
				4.166666666698246,
				6.122448979565321,
				6.12244897961267,
				4.081632653074482,
				5.88235294118696
	]
}
```

## HTTP behaviour

A few cross-cutting behaviours apply to the server as a whole, regardless of which endpoint is called.

**Rate limiting.** The login `POST /` is limited to `rate_limit_login_max` requests per minute per client IP (default 20), and `/api/v1/*` together with `/metrics` to `rate_limit_api_max` per minute per client IP (default 300). Over the limit, the server answers `429 Too Many Requests` — anyone polling the API in a tight loop should expect it and back off. Both limits are configurable; see [Settings](#settings).

**CORS is deny-by-default.** A browser client on another origin gets no `Access-Control-Allow-Origin` header at all unless that origin is listed in `cors_origins` in `config.ini`, so a browser-hosted dashboard (Grafana, a custom admin panel) cannot call the API cross-origin out of the box. To allow it, list the origins comma-separated:

```
cors_origins: https://grafana.example.com, https://dash.example.com
```

**Compression and conditional requests.** Responses are gzipped when the client sends `Accept-Encoding: gzip`, and carry an `ETag`; a client that repeats a request with `If-None-Match` gets a `304 Not Modified` when the body has not changed, skipping the payload.

**Security headers and request IDs.** Every response carries baseline security headers (`X-Content-Type-Options: nosniff`, `X-Frame-Options: SAMEORIGIN`, `Referrer-Policy: no-referrer`, and friends) and an `X-Request-Id` unique to that request. When `save_logs` is on, the same ID ends each access-log line in `nitr.log`, so a client-side error report can be matched against the server's log.

## Prometheus metrics

Nitr exposes a `/metrics` endpoint emitting the standard Prometheus exposition format, so Nitr becomes a drop-in scrape target for Grafana, Alertmanager, VictoriaMetrics, and any other monitoring stack that speaks Prometheus.

The endpoint sits behind the **same `x-api-key` header** as the JSON API — the exposed data is hardware detail and should not be public. Prometheus passes custom headers through `http_headers` in `scrape_config` (`secrets:` rather than `values:` so the key is redacted on Prometheus's own config page):

```yaml
scrape_configs:
  - job_name: nitr
    scheme: http
    metrics_path: /metrics
    static_configs:
      - targets: ["localhost:8000"]
    http_headers:
      x-api-key:
        secrets: [yourapikeyhere]
```

### Exposed metrics

All metrics use the `nitr_` prefix, base units (seconds, bytes), and `snake_case`. CPU time is a counter (cumulative); the rest are gauges reflecting host state at scrape time.

| Metric                       | Type      | Labels        | Description                                                     |
|------------------------------|-----------|---------------|-----------------------------------------------------------------|
| `nitr_cpu_seconds_total`     | counter   | `cpu`, `mode` | Cumulative CPU seconds per core and mode (user, system, idle...) |
| `nitr_ram_total_bytes`       | gauge     |               | Total RAM in bytes                                              |
| `nitr_ram_free_bytes`        | gauge     |               | Free RAM in bytes                                               |
| `nitr_ram_used_bytes`        | gauge     |               | Used RAM in bytes                                               |
| `nitr_disk_free_bytes`       | gauge     | `mountpoint`  | Free disk space in bytes                                        |
| `nitr_disk_size_bytes`       | gauge     | `mountpoint`  | Total disk size in bytes                                        |
| `nitr_disk_used_bytes`       | gauge     | `mountpoint`  | Used disk space in bytes                                        |

CPU usage is not a separate metric; derive it from the counter with PromQL, e.g. average busy fraction per core over 5m:

```promql
1 - avg(rate(nitr_cpu_seconds_total{mode="idle"}[5m])) by (cpu)
```

Per-interface bandwidth is **not** exposed yet. `bandwidth.Info` derives a per-second delta by reading netdev counters twice with a 1s sleep, and a blocking scrape endpoint causes Prometheus scrape timeouts. It will be added once a background sampler lands.

Example scrape with curl:

```bash
curl http://localhost:8000/metrics -H 'x-api-key: yourapikeyhere'
```

```text
# HELP nitr_cpu_seconds_total Cumulative seconds the CPU has spent in each mode, per core. Counter; derive utilisation with avg(rate(nitr_cpu_seconds_total[5m])) by (mode).
# TYPE nitr_cpu_seconds_total counter
nitr_cpu_seconds_total{cpu="0",mode="idle"} 1.2345678e+06
nitr_cpu_seconds_total{cpu="0",mode="user"} 3.4567890e+05
# HELP nitr_disk_free_bytes Free disk space in bytes.
# TYPE nitr_disk_free_bytes gauge
nitr_disk_free_bytes{mountpoint="/"} 1.2345678e+07
# HELP nitr_ram_total_bytes Total RAM in bytes.
# TYPE nitr_ram_total_bytes gauge
nitr_ram_total_bytes 8.3319750656e+09
```

## Health and readiness probes

Nitr exposes two unauthenticated probes at the root of the server — `GET /health` and `GET /ready` — for Docker, Compose, Kubernetes, and any external uptime checker. Both are registered on the root app **before** the `x-api-key` middleware and the panel session auth, so they answer with **no API key and no login**, and never redirect to the login page. They are deliberately not under `/api/v1`.

`GET /health` is the liveness probe. It performs no I/O, touches no collector and no database handle, and cannot fail for reasons unrelated to the process being alive:

```bash
curl http://localhost:8000/health
{"status":"ok","version":"0.9.0"}
```

`GET /ready` is the readiness probe. It reports `200` only once `nitr.db` is present at its resolved location (under `--data-dir`, else the working directory); `503` otherwise:

```bash
curl http://localhost:8000/ready
{"status":"ready"}
```

It does an `os.Stat(database.DBPath())` — the resolved `nitr.db` path, honouring `--data-dir` — and nothing more. That is a narrow, honest check: it confirms the database file exists — which only happens once the server's setup has run — but it does **not** confirm bolt can be opened right now, nor that the DB is uncorrupted. If you need a true open-and-read probe, wait for that to land — do not treat `/ready` as a database-connectivity check, because it is not one.

## API v1

### Root endpoint

```
http://localhost:8000/api/v1
```

### Available endpoints

These endpoints return system and hardware information about your **host**. Check the [example](#example) for a better understanding.

| Verb | Endpoint   |
|------|------------|
| GET  | /          |
| GET  | /cpu       |
| GET  | /bios      |
| GET  | /bandwidth |
| GET  | /chassis   |
| GET  | /disks     |
| GET  | /drives    |
| GET  | /devices   |
| GET  | /gpu       |
| GET  | /host      |
| GET  | /isp       |
| GET  | /network   |
| GET  | /processes |
| GET  | /ram       |
| GET  | /baseboard |
| GET  | /product   |
| GET  | /memory    |
| GET  | /swap      |
| GET  | /loadavg   |
| GET  | /sensors   |

### Time-range queries

The four usage-metric endpoints — `/cpu`, `/ram`, `/disks`, `/bandwidth` — accept `?from=`, `?to=`, and `?resolution=` query parameters when [history retention](#metric-history-retention) is enabled. With **any** of them present, the response switches from the instantaneous payload to a series of retained samples, oldest first:

```json
[{"timestamp":"2026-07-29T15:44:28.502661692Z","data":{"vendor":"AuthenticAMD","model":"AMD Ryzen 9 9900X 12-Core Processor","cores":12,"threads":24,"clockSpeed":4391.661,"usage":2.83,"usageEach":["..."]}}]
```

Each `data` carries the exact payload the endpoint's instantaneous form returns (for `/disks` and `/bandwidth` that payload is an array). `from` and `to` accept RFC3339 (`2026-07-29T03:00:00Z`) or bare Unix seconds, and default to the oldest retained sample and now; `resolution` (seconds, default `0` = every stored sample) thins the series to at most one sample per window, keeping the first sample in each — payloads are never averaged or altered.

**With none of the parameters present, the response is byte-identical to before range queries existed** — existing integrations are unaffected. With retention disabled (the default), passing any range parameter returns `400` with a message naming the key to set:

```json
{"message":"metric history retention is disabled; set history_enabled (off by default) to use from/to/resolution","status":400}
```

### JSON data references

The field-by-field shape of every endpoint above — types, descriptions, privilege notes, query parameters — is **generated, not hand-written**, so it cannot drift from the code the way a transcribed table can:

- [`docs/openapi.json`](docs/openapi.json) is the OpenAPI 3.1 spec checked into this repo and the source of truth everything else below is built from. A CI check (`TestOpenAPISpecCoversAllRegisteredRoutes`) fails the build if a route registered in `main.go` has no matching entry here.
- `GET /openapi.json` serves that same file live from the running instance — point any OpenAPI-aware client generator at it for a free SDK in your language of choice.
- The panel renders it at `/docs` (client-side, from `/openapi.json`, so the page itself can never go stale independent of the spec).

## Settings

Nitr reads its settings from `config.ini` in the working directory by default. Every setting can also be supplied as a **`NITR_` environment variable** (uppercase, e.g. `NITR_PORT`, `NITR_SAVE_LOGS`, `NITR_CORS_ORIGINS`), which is what makes the Docker image configurable without bind-mounting a config file. Configuration resolves, highest priority first:

> **`--flags`** > **`NITR_*`** environment variables > config file > built-in defaults

| Flag | Env var | Config key | Default |
|---|---|---|---|
| `--config` | `NITR_CONFIG` | — | `./config.ini` |
| `--port` | `NITR_PORT` | `port` | `8000` |
| `--host` / `--bind` | `NITR_BIND_ADDRESS` | `bind_address` | `0.0.0.0` (all interfaces) |
| `--data-dir` | `NITR_DATA_DIR` | `data_dir` | working directory |
| `--history-enabled` | `NITR_HISTORY_ENABLED` | `history_enabled` | `false` |
| `--history-interval` | `NITR_HISTORY_INTERVAL` | `history_interval` | `10` (seconds) |
| `--history-retention-hours` | `NITR_HISTORY_RETENTION_HOURS` | `history_retention_hours` | `24` (hours) |

`--bind` is accepted as an alias of `--host`. Keys without a dedicated flag — `save_logs`, `cors_origins`, `metrics_push_interval`, and the rest below — are still settable via their `NITR_` env var.

> The config file is named `config.ini` but is **parsed as YAML**: write `key: value` lines, not INI `key=value` or `[sections]` — real INI syntax is silently ignored. The file keeps its `.ini` name rather than being renamed, to avoid breaking existing installs.

### Server Port

By default, the web server starts on port 8000.

```
port: 3000
```

### Bind Address

The interface address the server listens on, via the `bind_address` key, the `--host` (or `--bind`) flag, or the `NITR_BIND_ADDRESS` env var. The default is `0.0.0.0` — **all interfaces** — which preserves the previous behaviour: the server always listened on every interface, and with nothing set it still does. Setting `127.0.0.1` makes **localhost-only binding possible for the first time**:

```
bind_address: 127.0.0.1
```

For a tool that exposes host telemetry, restricting it to loopback is a security-relevant capability — a loopback-bound server is not reachable from the network.

### Data Directory

The directory holding `nitr.db`, via the `data_dir` key, the `--data-dir` flag, or the `NITR_DATA_DIR` env var. Defaults to the working directory. The directory is created if it does not exist.

```
data_dir: /var/lib/nitr
```

This relocates **`nitr.db`** and, when `save_logs` is on, **`nitr.log`**; `config.ini` is not affected and stays in the working directory (use `--config` to relocate it).

### Open Browser on Startup

If true, opens your default web browser on server startup.

```
open_browser_on_startup: true
```

### Enabling Logs

If true, logs are saved in `nitr.log` file, otherwise logs are printed out to console.

```
save_logs: true
```

### Enable SSL

If true, server starts using HTTPS protocol.  Certificate and Key must be provided
```
ssl_enabled: true
ssl_certificate: /path/to/file.crt
ssl_certificate_key: /path/to/file.key
```

### Rate Limits

Per-client-IP request caps, in requests per minute. Exceeding one returns `429 Too Many Requests` (see [HTTP behaviour](#http-behaviour)). Unset or invalid values fall back to the defaults.

```
rate_limit_login_max: 20
rate_limit_api_max: 300
```

### Cross-Origin (CORS) Access

Comma-separated list of browser origins allowed to call the server cross-origin. Empty (the default) denies all cross-origin browser access — see [HTTP behaviour](#http-behaviour).

```
cors_origins: https://grafana.example.com, https://dash.example.com
```

### Live Metrics Push Interval

Seconds between live CPU/RAM/disk pushes from the server to the web panel over the `/status` socket. Defaults to 3; values below 1 are clamped to 1.

```
metrics_push_interval: 3
```

### Metric History Retention

**Off by default.** When enabled, nitr retains CPU, RAM, disk, and bandwidth samples in `nitr.db`, so the four usage-metric endpoints can answer [time-range queries](#time-range-queries):

```
history_enabled: true
history_interval: 10            # seconds between retained samples
history_retention_hours: 24     # samples older than this are pruned
```

**Why it defaults to off** — this is a deliberate product decision, not an oversight: the sampler writes to `nitr.db` every `history_interval` seconds, and sustained small writes wear flash/SD storage. Raspberry Pi is an explicitly targeted deployment, so retention is strictly opt-in — understand that tradeoff before enabling it on an SBC.

At the defaults the database reaches a steady state of **8640 samples per metric** (24h at 10s): all four metrics are written in a single transaction (one fsync per tick), pruning rides in the same transaction, and the file plateaus at that high-water size rather than growing without bound. With retention disabled, no history is ever written and `nitr.db` contains no history bucket.

## Platform support

Nitr publishes release binaries for **Linux** and **Windows**, on **amd64**, **386** (32-bit), and — Linux only — **arm64**:

| OS      | amd64 | 386 | arm64 |
|---------|-------|-----|-------|
| Linux   | yes   | yes | yes   |
| Windows | yes   | yes | no    |

Download them from the [latest release](https://github.com/bitcav/nitr/releases/latest).

Every push runs the full test suite on two CI runners — `ubuntu-latest` and `windows-2025` — and on each leg additionally builds the real binary and runs `nitr version`, asserting it exits 0 and prints a sane version string. The 386 builds in the table above are cross-compiled by CI but are not executed there.

**linux/arm64** (Raspberry Pi, Odroid, ARM VPS instances) is a supported, published target: CI cross-compiles it, a probe job executes the binary on a real ARM64 runner (`ubuntu-24.04-arm`) and verifies the endpoints, and `nitr_linux_arm64` ships with the release artifacts. One caveat: endpoints that read SMBIOS/DMI — `/api/v1/bios`, `/chassis`, `/baseboard`, `/product` and `/memory` — depend on data most ARM single-board computers simply do not provide (a Raspberry Pi has no SMBIOS at all), so expect them to be empty or unavailable there. The CI probe runner is a cloud VM that *does* expose DMI, so its populated SMBIOS endpoints do not generalise to SBC hardware. That is a platform property, not a bug. The endpoints that matter most for monitoring — CPU, RAM, disk, network, host, processes — go through `/proc` and work.

## Powered by

* [Fiber](https://gofiber.io/) - The web framework used
* [bbolt](https://github.com/etcd-io/bbolt) - Database
* [UIKit](https://getuikit.com/) - Front-End framework
* [gopsutil](https://github.com/shirou/gopsutil) - psutil for Golang
* [ghw](https://github.com/jaypipes/ghw) - Golang HardWare discovery/inspection library
* [go-smbios](https://github.com/digitalocean/go-smbios) - Detection and access to System Management BIOS

nitr

nitr 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

nitr

nitr 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README