RunState Agent — Installation Guide

The RunState agent is a lightweight process you install on your local network. It polls your UniFi controller locally and sends data outbound to RunState cloud — no inbound firewall rules required.

Use this path when your controller is a Dream Machine, UDM-Pro, or any controller on a private IP with no public URL.

Pre-install: Create a dedicated UniFi user

Create a read-only service account on your UniFi controller for the agent. Do not use your personal admin credentials.

1. Log in to your UniFi controller
2. Go to Settings → Admins & Users → Add Admin
3. Set Role: Site Admin (required for config API access)
4. Note the username and password — you will enter them during installation

Install (one-liner)

Run this on a Linux machine that has network access to your UniFi controller (Ubuntu 20.04+ or Debian 11+ recommended). You will need the agent token from the RunState dashboard.

curl -fsSL https://stage.runstate.one/install.sh | sudo bash -s -- \
  --token <your-token-from-runstate> \
  --controller https://192.168.1.1

Replace 192.168.1.1 with your controller's local IP or hostname. The installer will prompt for your UniFi username and password — they are entered interactively and never stored in your shell history.

What the installer does:

1. Checks for Node.js 18+; installs it if absent (via NodeSource)
2. Downloads and installs the agent package globally
3. Prompts for your UniFi username and password
4. Verifies the connection to your controller
5. Writes an encrypted config file to /etc/runstate-agent/config.json (root-only, mode 600)
6. Registers a systemd service that starts automatically on boot
7. Runs a first poll and sends your initial snapshot to RunState

A successful install looks like:

UniFi username: backup
UniFi password:

==> Installing RunState Agent v0.1.0

==> Node.js v22.x.x ready.
==> Downloading runstate-agent-0.1.0.tgz...
==> Installing agent globally...
==> Configuring agent...
1/4  Verifying controller connection…
     Connected to UniFi controller.
2/4  Writing config to /etc/runstate-agent/config.json…
     Config written (mode 600).
3/4  Registering systemd service…
     Service registered and started.
4/4  Performing first poll…
     First poll complete.

RunState agent installed successfully.
Controller: https://192.168.1.1
Ingest:     https://rs-dev-functions.azurewebsites.net/api/agent/ingest

Check status with: systemctl status runstate-agent

Verify it's running

systemctl status runstate-agent

You should see Active: active (running). The RunState dashboard will show the controller as connected within 30 seconds of the first poll completing.

Checking logs

journalctl -u runstate-agent -f

A healthy agent looks like:

[runstate-agent] Starting poll loop — interval 900s
[runstate-agent] Poll complete — changeCount: 0

Troubleshooting

"UniFi login failed: HTTP 400 / 401" Check your username and password. The account needs at least Site Admin access.

"UniFi login failed: HTTP 500 / connection refused" The --controller URL can't be reached from this machine. Check the IP and confirm the machine is on the same network as the controller. Try curl -k https://192.168.1.1 to test reachability.

Service shows "failed" in systemctl Run journalctl -u runstate-agent --no-pager -n 50 to see the full error. The most common cause is a credentials problem — re-run the installer with corrected credentials.

Token already used / invalid token Each token is permanent once installed. If you see a 401 error in logs after a previously working install, contact RunState — the token may need rotation.

Security notes

• Controller credentials are encrypted at rest using AES-256-GCM. The encryption key is derived from your agent token.
• The config file at /etc/runstate-agent/config.json is readable by root only (mode 600).
• The agent only makes outbound HTTPS connections — no inbound ports are opened.
• Each token is scoped to a single controller.

Uninstalling

sudo systemctl disable --now runstate-agent
sudo rm /etc/systemd/system/runstate-agent.service
sudo rm -rf /etc/runstate-agent
sudo systemctl daemon-reload
sudo npm uninstall -g @runstate/agent

Updating

When RunState provides a new version:

curl -fsSL https://stage.runstate.one/install.sh | sudo bash -s -- \
  --token <your-token> \
  --controller https://192.168.1.1

The installer is idempotent — re-running it upgrades the agent and restarts the service.

Advanced: offline / manual install

If the one-liner is not available, you can install manually from the .tgz package:

# Install Node.js if needed
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install the agent
sudo npm install -g ./runstate-agent-0.1.0.tgz

# Run the install command (prompts for username and password interactively)
sudo runstate-agent install \
  --token <your-token-from-runstate> \
  --controller https://192.168.1.1

What gets polled

The agent polls these UniFi configuration endpoints every 15 minutes:

| Endpoint | What it covers | |---|---| | Firewall rules | All LAN/WAN firewall rules | | Network configuration | VLANs, DHCP, routing | | Wireless networks | SSIDs, security settings | | Port forwarding | NAT rules | | Static routes | Custom routing entries | | Switch port profiles | Port configurations | | SMTP settings | Email relay configuration | | Device status | Connected device inventory |

All data is sent to RunState cloud where diffs, alerts, and snapshots are processed. The agent does not compute diffs or store data locally.