Back

Install Agent

One command on any server. Auto-detects OS, cloud provider, and hardware. Your node appears in the dashboard within seconds.

Run on your server:

Works on any modern Linux distribution.

Optional. Without a token, register first then claim the node from the dashboard.

$ curl -sSL https://nodestral.web.id/install.sh | sh -s --
Installs to ~/.local/bin. If systemd user service is available, sets up auto-start. Otherwise runs in background — will need manual restart after reboot.

What happens

  1. 01Detects OS and CPU architecture
  2. 02Downloads the correct binary
  3. 03Installs to ~/.local/bin/ (no root)
  4. 04Sets up user-level systemd service (if available)
  5. 05Registers with Nodestral (unclaimed)
Security

Runs unprivileged. Outbound-only HTTPS to nx.nodestral.web.id. No inbound ports. Source on GitHub.

FAQ

What does the agent do?
Collects system metrics (CPU, RAM, disk, network), detects cloud provider, auto-discovers services, Docker containers, ports, certificates, SSH users. Sends data to Nodestral API every 30 seconds.
System requirements?
Any modern Linux (Ubuntu 20.04+, Debian 11+, CentOS 8+, Arch). Single ~17MB static binary, zero dependencies. macOS also supported for testing.
Does it need root/sudo?
By default, no — it runs in user space without sudo. If you want it to auto-start on boot as a system service, use the --system flag (requires sudo). The system service runs as a dedicated `nodestral` user with minimal privileges.
How to uninstall?
User mode: rm ~/.local/bin/nodestral-agent && rm -rf ~/.config/nodestral && systemctl --user disable nodestral-agent. System mode: sudo systemctl stop nodestral-agent && sudo systemctl disable nodestral-agent && sudo rm /usr/local/bin/nodestral-agent && sudo rm -rf /etc/nodestral
Is it open source?
Yes. github.com/nodestral/agent — MIT license, fully auditable.
What about the dashboard?
The dashboard shows all metrics from PostgreSQL. Pro users can optionally export metrics to Prometheus, Grafana Cloud, or Datadog for advanced querying.
What are the plans?
Free: 2 nodes, dashboard metrics, 7-day retention. Pro: unlimited nodes, metrics export to Prometheus/Grafana Cloud, 30-day retention.