Installation#

Prerequisites#

To install our Go Agent you will need:

  • Your Organization’s API Token: Found or regenerated in the Organization tab

  • Agent ID: Displayed after creating a new agent in the dashboard

  • Network Connection: Target host must be able to make outbound HTTP/HTTPS requests to our server

  • Supported System: A supported operating system and architecture (see requirements)

  • Root / Sudo Access: Required to install and run the agent as a systemd service on the host

Overview & Functionality#

The agent simplifies monitoring by automatically gathering core system metrics and system information. Further metric configurations can conveniently be managed via the Dashboard.

The collected baseline metrics & system information include:

  • Operating system & version

  • Hostname

  • System architecture (arm64, amd64, etc.)

  • Hardware specifications (CPU core count, total RAM in GB, total disk capacity in GB)

  • CPU usage (%)

  • RAM usage (%)

  • Disk utilization (%)

  • System uptime

Step-by-Step Setup#

Step 1: Obtain / Create Your Organization API Token#

  1. In the WatchGrid Dashboard, navigate to the Organization tab.

  2. If you already have an active, saved API Token, you can use it (WG_TOKEN).

  3. Creating / Re-creating an API Token: To generate a new token (e.g. for your first agent or if you do not have the token saved), delete the existing token from the organization token list and create a new token.

    Wichtig

    Upon creation, the new API Token is displayed only briefly in a system message/toast notification in the dashboard UI! Make sure to copy the token immediately and store it securely.

    Warnung

    Deleting an existing API token revokes authentication for any installed agents using that token. Affected agents will need to be updated with the newly created token (see Updating API Tokens).

Step 2: Create Your First Agent in the Dashboard#

  1. Go to the Agent Overview Dashboard.

  2. Click the „Add Agent“ button in the top right corner.

  3. Enter a name for your server/agent (e.g. web-server-01).

  4. Once saved, your unique Agent ID (UUID) will be displayed. Copy this Agent ID (WG_AGENT).

Step 3: Run the One-Liner Installation on the Target Host#

Open a terminal/SSH session on your target host and execute the single-line command below. Replace <AGENT_ID> and <API_TOKEN> with your copied values from Steps 1 and 2:

curl -sfL https://wgri.de/install | WG_AGENT="<AGENT_ID>" WG_TOKEN="<API_TOKEN>" sh -

Example:

curl -sfL https://wgri.de/install | WG_AGENT="123e4567-e89b-12d3-a456-426614174000" WG_TOKEN="wg_live_abc123xyz..." sh -

Step 4: Verify Installation#

Upon successful execution, the agent is automatically configured and started as a systemd service (watchgrid.service).

  • Check the service status on the server:

    systemctl status watchgrid.service

  • In the WatchGrid Dashboard, the new agent will show up as Online within a few seconds and begin transmitting metrics.

Architecture & Configuration#

Systemd Service Mode#

By default, the Go Agent runs as a continuous systemd service (watchgrid.service). It starts automatically on system boot and performs real-time monitoring in the background.

Local Configuration Cache#

The agent operates using a pull-based model. On startup (and periodically during metric collection), the agent fetches the latest configuration from the WatchGrid server. This configuration is stored locally as a cache file at /etc/watchgrid/config.json (or ./config/config.json in local development).

If the WatchGrid server becomes temporarily unavailable, the agent seamlessly falls back to this local cached configuration to ensure uninterrupted operation.

Service and Port Monitoring#

In addition to resource utilization metrics (CPU, RAM, Disk), the agent monitors network ports and systemd services.

  • Port Monitoring: The agent inspects /proc/net/tcp and /proc/net/tcp6 for listening ports. Any open ports not listed in the server-provided whitelist are flagged as anomalies and reported to the server (localhost bindings on 127.0.0.1 or ::1 are ignored).

  • Service Monitoring: The agent uses systemctl is-active --quiet <service_name> to verify specified systemd services. If a monitored service is stopped, it is flagged and reported immediately.