statsd installation and CLI documentation

statsd is the System Stats monitoring agent for Linux, macOS and Windows. It collects machine metrics and publishes them to your dashboard. It is unrelated to the StatsD metrics aggregation protocol.

1. Create a System Stats account or sign in to your existing account.
2. Follow the installation instructions for Linux, macOS, Windows or Docker.
3. Follow the installer's login instructions. Open the authorization link in a browser and approve the machine.
4. Run statsd status using the same configuration directory and permissions as the installation, then open the dashboard to confirm that metrics are arriving.

On macOS, you can use Stats instead of statsd if you prefer a menu bar app.

The native installers download the appropriate binary, register a background service and start it. A manual statsd install only registers the service; follow it with statsd start.

Requires systemd, root or sudo access, and a supported architecture: x86_64, arm64, or 32-bit ARM (armv6/armv7).

The installer places the binary in /usr/local/bin and registers the statsd systemd service. Then authorize the machine:

Open the printed link in a browser. Omit sudo if you are already root. Use the same invoking user as the installation so the service and CLI share a configuration directory. If systemd is unavailable, use a foreground run or a container.

Supports Apple silicon and Intel Macs. Administrator access is required to install the launchd service.

The installer places the binary in /usr/local/bin and registers a system LaunchDaemon. It runs independently of your desktop session and starts at boot.

Open the printed link and approve the machine. Use the same invoking user as the installation. For a desktop app, follow Stats on macOS.

Supports x86_64 and arm64. Open PowerShell as Administrator:

The installer places statsd.exe in %ProgramFiles%\statsd, adds it to PATH, and registers and starts the Windows service. In the same Administrator PowerShell session:

Open the printed link and approve the machine. Keep using the same configuration directory, especially when switching Windows accounts. NVIDIA GPU metrics require nvidia-smi; AMD and Intel live GPU metrics are currently unavailable on Windows.

Create a compose.yaml file:

Start the container and read the authorization link from its logs:

Open the link in a browser and approve the machine. Preserve the statsd-data volume when recreating the container: it stores credentials and the device identity.

Metrics reflect the resources visible inside the container. This example does not expose host GPU devices, the host filesystem or the Docker socket. Use a native installation when you need direct access to host metrics.

For optional Docker metrics on a Linux host, add this socket mount under the service's volumes:

Socket access allows Docker API operations, including container control; the :ro mount does not make that API read-only. See remote control for disabling dashboard commands. Docker Desktop runs containers inside a VM, so container metrics do not represent the macOS or Windows host.

Update the container by pulling the image and recreating it with the same volume:

Place the binary for your operating system and architecture in its permanent location and make it executable on Linux/macOS. Run statsd version to check it, then authorize with statsd login.

To run it in your terminal:

To register a background service on Linux/macOS:

On Windows, run statsd install and statsd start from Administrator PowerShell. If the executable is not on PATH, use its full path (or ./statsd.exe from its directory).

For a source build, use the Go version specified in statsd's go.mod. macOS builds also require CGO and the Xcode command-line tools. From the statsd source directory:

On Windows, build with go build -o statsd.exe . and invoke ./statsd.exe.

Stats is the macOS menu bar alternative to statsd. Use it to view metrics locally and connect your Mac to the same System Stats dashboard.

1. Download Stats, open the disk image, and move Stats to Applications.
2. Launch Stats and open its settings.
3. Find the System Stats section and choose Sign in under Authorization. Complete authorization in your browser.
4. Enable Monitoring in that section and check your machine in the dashboard.
5. Enable launch at login if you want Stats to start with your desktop session.

Stats uses its own settings. The statsd commands and configuration below apply to the CLI agent. For monitoring independently of a signed-in desktop session, use statsd's launchd service.

Run statsd login on the machine you want to monitor. Use the privileges and configuration directory printed by the installer. The command prints a device authorization URL and waits for approval.

Open that URL in a browser, sign in to your System Stats account, and approve the machine. On a headless server, you can open the URL on another computer or phone. Leave the command running until it confirms registration. If a code expires, the CLI requests a fresh one; use the latest printed URL.

Credentials are stored in the configuration directory and the daemon refreshes access tokens as needed. The CLI and daemon must use the same directory. A successful login authorizes the device; it does not start a manually installed service.

status reports the daemon lock and stored authorization state. Confirm delivery by checking the dashboard; local status alone does not prove metrics reached it.

statsd logout revokes authorization. statsd deregister releases the device from its account and revokes authorization. To move a device to another account, deregister while it is still authorized, then log in again:

For containers, the daemon starts the authorization flow automatically when credentials are missing. Read the URL with docker compose logs -f statsd.

statsd collects CPU, RAM, GPU, disk, network, Docker and Proxmox metrics. Optional readers depend on available hardware, local tools and permissions. Collection intervals are configurable; there are no per-module enable/disable CLI switches.

Processor usage, load and frequency. Default interval: 1s.

Available metrics depend on the operating system and hardware.

Memory usage, available memory and swap. Default interval: 1s.

Memory pressure is available on macOS.

GPU activity, memory and supported sensors. Default interval: 5s.

NVIDIA requires nvidia-smi. AMD and Intel live metrics are not supported on Windows.

Storage capacity and disk I/O. Default interval: 1s.

Devices and filesystems must be visible to the agent.

Interface addresses and transfer rates. Default interval: 1s.

Only interfaces visible to the agent are reported.

Container state, resource usage and health. Default interval: 3s.

Requires a local Unix socket at /var/run/docker.sock or /run/docker.sock and Docker API 1.44 or newer.

Virtual machines and LXC containers. Default interval: 5s.

Requires the local Proxmox tools on a Proxmox node.

Show saved intervals (or built-in defaults), inspect one module, change its interval, or restore its default:

Changes are saved and apply to the running daemon without a restart, unless that module has a flag or environment override. Use the service's configuration directory and sufficient permissions to write it. Module names are case-insensitive.

Intervals must be positive durations with units, such as 500ms, 2s or 1m. Zero and negative values are rejected. default removes the saved override; it does not override an explicit flag or environment variable.

Override a module for a foreground run:

Or use an environment variable in a POSIX shell:

In PowerShell:

Runtime overrides are not saved. statsd interval shows saved values or defaults, not the effective flag/environment overrides of another process. Stop an installed service before running a second daemon with the same configuration directory.

Intervals schedule read starts. Slow reads skip missed ticks instead of overlapping. Each read receives a 15-second context deadline, though native calls that cannot be interrupted may take longer.

The default file is ~/.statsd/config.json (%USERPROFILE%\.statsd\config.json on Windows). Choose another directory with --config-dir or STATSD_CONFIG_DIR:

On Windows, use a Windows path, for example statsd --config-dir "C:\ProgramData\statsd" status.

Under sudo, the default follows the invoking user's home. Service installation pins the resolved directory, so continue using it for login, status and configuration changes. An explicit directory flag takes precedence over STATSD_CONFIG_DIR.

Interval precedence: command-line flag → environment variable → saved setting → built-in default.

The file also contains credentials and device identity. Prefer CLI commands for changes and remove credentials before sharing diagnostics. Saved intervals use interval_cpu, interval_ram, interval_gpu, interval_disk, interval_network, interval_docker and interval_proxmox, with duration strings as values.

The saved control setting defaults to enabled; manage it with enable-control and disable-control. The saved update setting also defaults to enabled and controls remote update availability; the string "false" disables it. There is no dedicated CLI switch for that setting.

Flags passed to statsd install are not automatically forwarded to the service. Use saved intervals for persistent service configuration. For runtime environment overrides, configure the environment in the service manager and restart the service.

API, MQTT and authorization hosts are fixed in the build. There are no runtime host overrides.

Running statsd without a command is equivalent to statsd run: it runs the daemon in the current process. Use start and stop for an installed system service.

Use root/sudo on Linux and macOS, or Administrator PowerShell on Windows, for service management. Keep the executable in its installed location and use the pinned configuration directory.

On Linux, statsd logs follows the systemd journal. On macOS and Windows, it prints statsd.log.old and statsd.log from the configuration directory when present; it does not follow new lines. Foreground runs log to stderr. For containers, use docker compose logs -f statsd.

Use statsd update for native installations, with permission to replace the installed executable and manage its service. For containers, pull or rebuild the image and recreate the container with the same configuration volume.

statsd uninstall removes the service registration, not the executable or configuration. To release the device from your account, run statsd deregister before removing the installation. You can then remove the installed binary and configuration if you no longer need them.

Remote control is enabled by default. It allows supported dashboard commands, including agent restarts, machine reboots, container operations and container log streaming. Disable it locally with:

Re-enable it with:

These commands persist the setting in the configuration directory. The running agent reconciles changes with the backend. Metric collection continues when remote control is disabled. Remote updates have a separate update setting described under Configuration; disable-control does not disable remote updates.

Start with the daemon status, local diagnostics and logs. Use the same configuration directory as the service:

doctor collects local samples without logging in, creating configuration or publishing telemetry. Missing optional hardware is reported as unavailable, separately from collection errors. A single sample may not contain rates that need a previous measurement. Exit code 1 indicates collection errors.

Linux GPU diagnostics show raw temperatures in millidegrees Celsius and power in microwatts. Normalized metric samples use Celsius and watts. Successful diagnostics confirm local collection, not delivery to the dashboard.

The following reference lists statsd's commands, flags, arguments, environment variables and defaults.

Use statsd --help (or -h) for general help and statsd <command> --help for command-specific help. statsd help <command> (alias h) is also supported. --version, -v, version and v print the version.

Legacy command spellings such as --login and -login are accepted for compatibility; use the subcommand form statsd login in new scripts. Invalid usage exits with code 2; operational failures generally exit with code 1.

statsd completion <shell> prints a completion script. Supported shells are bash, zsh, fish and pwsh (PowerShell). For example, enable completion in the current zsh session:

Use bash in place of zsh for a bash session. For fish or PowerShell, save the output of statsd completion fish or statsd completion pwsh and load it through your shell's configuration. The hidden --generate-shell-completion flag is used by those scripts to request completion candidates.

Run without a command to start the daemon. Use start/stop to control an installed service.

Collect and publish machine metrics.

Usage:

Global flags:

Check local metric readers and GPU sensor access.

Collect one local sample per module without logging in or publishing. Counter-based rates need a previous sample and may be absent or zero. Missing optional hardware is reported as unavailable. Linux sensor values use raw sysfs units; normalized samples report temperature in Celsius and power in watts. Exit code 1 indicates collection errors.

Usage:

The following flags are supported:

Run the daemon in this process.

Intervals schedule read starts; slow reads skip missed ticks without overlapping. Reads receive a 15-second deadline. Saved interval changes apply live unless overridden by a flag or environment variable.

Usage:

Authorize this device.

Usage:

Revoke authorization.

Usage:

Release this device from its account.

Usage:

Show daemon and authorization status.

Usage:

Show system hardware information.

Usage:

Update statsd to the latest version.

Usage:

Show daemon logs.

Usage:

Enable remote control.

Usage:

Disable remote control.

Usage:

Print the version.

Usage:

Show or persist a module collection interval.

Modules: cpu, ram, gpu, disk, network, docker, proxmox. Example: statsd interval gpu 2s Changes apply live unless overridden by a flag or environment variable. Use 'default' to reset an interval.

Usage:

Install the system service.

Usage:

Uninstall the system service.

Usage:

Start the system service.

Usage:

Stop the system service.

Usage:

Restart the system service.

Usage: