Getting Started with the Agent

Overview

This guide introduces the AppStatus Agent and covers:

• Introduction to the Agent
• Installation across platforms
• Data collected by the Agent (8 collectors)
• Agent configuration file reference
• Advanced configurations and features
• Troubleshooting

What is the AppStatus Agent?

The AppStatus Agent is software that runs on your hosts. It collects system metrics, process data, logs, security events, container stats, file integrity changes, HTTP probe results, and active sessions from hosts and sends them to AppStatus, where you can analyze your monitoring and performance data in real time.

The Agent can run on:

• Local hosts — Linux (AMD64, ARM64), macOS, Windows
• Containerized environments — Docker, Kubernetes
• Cloud platforms — AWS, GCP, Azure, any cloud VM
• Configuration management — Ansible, Chef, Puppet, Terraform

With 8 built-in collectors, the Agent can collect 75–100 system-level metrics every 10–30 seconds. It streams live telemetry over gRPC with TLS 1.2+ encryption, batching data every second for efficient delivery. The Agent uses bidirectional streaming for both telemetry and logs, with automatic reconnection and exponential backoff.

The Agent supports building for 6 platforms: linux/amd64, linux/arm64, darwin/amd64, darwin/arm64, windows/amd64, windows/arm64.

The Agent Configuration File

The Agent's main configuration file is agent.yaml. The required parameters are:

• Your AppStatus Workspace API Key, which is used to authenticate the Agent's data with your workspace.
• Your AppStatus endpoint (agent.appstatus.io:443).

See the sample agent.yaml.example file for all available configuration options. You can adjust the Agent configuration to enable/disable individual collectors, set collection intervals, define log paths, and configure security detection rules.

Installation

To get started, select your platform

Agent Metrics

The Agent reports the following metrics to AppStatus about itself. These metrics provide information about which hosts have running Agents, when each Agent started, and the health of the telemetry pipeline.

Service Checks

The Agent provides the following service checks:

• appstatus.agent.up — Returns OK if the Agent connects to AppStatus via gRPC.
• appstatus.agent.collector.status — Returns CRITICAL if a collector is unable to collect data; otherwise returns OK.
• appstatus.agent.heartbeat — Returns OK when the 30-second heartbeat is delivered successfully.

Advanced Configuration

Differences Between Agent for Hosts and Containers

There are key differences between installing Agents on a host and in a containerized environment:

Setting Labels through the Configuration File

Labels add metadata to your metrics and events. They allow you to scope and filter your data in AppStatus dashboards. When data is sent from multiple hosts, labeling allows you to narrow down to the data most relevant to your team.

After updating labels, restart the Agent. Labels will appear on all metrics, events, and logs sent by this Agent. You can filter agents by label in the AppStatus inventory view.

Batching and Send Configuration

The Agent batches collected data and sends it over gRPC streams. You can tune the batching behavior:

Logging Configuration

Offline Buffering

When the connection to AppStatus is lost, the Agent buffers data locally and retries with exponential backoff (up to 60s delay, infinite retries):

Agent Overhead

The Agent is designed to be lightweight. Expected resource consumption with all collectors enabled:

Actual usage depends on the number of enabled collectors, collection intervals, number of running processes/containers, and log volume. The single Go binary has minimal dependencies and runs efficiently on low-resource instances.

Troubleshooting

For help troubleshooting the Agent:

Hardening Checklist

• Use least-privilege mounts and read-only paths when running in containers.
• Rotate ingestion credentials and audit secret access on a schedule.
• Document distribution-specific overrides to avoid missing security events.
• Run platform-specific validation after every config or agent version change.
• Enable TLS in all production environments — never disable tls.enabled.
• Pin agent image/binary versions and track release notes for updates.

Step-by-Step Setup

The AppStatus agent is a small program you install on your servers, containers or Kubernetes nodes. It collects system metrics (CPU, memory, disk, network), processes, logs, security events and Docker container stats, then streams them back to AppStatus over an encrypted gRPC connection. Setup takes about 5 minutes per host — most of it is copying the install command and pasting your API key.

1. 1

   Open the Agents section

   The Agents page lists every host streaming telemetry to your workspace, plus an "Add agent" button that walks you through registration. Online agents show a green dot; offline ones show red with a "last seen" timestamp.

   WhereSidebar → Agents
2. 2

   Click "+ Add agent" and pick the platform

   A wizard opens. Choose the platform that matches your host: Linux, macOS, Windows, Docker container, or Kubernetes. Each platform shows different install instructions on the next step.

   WhereAgents → + Add agent → Platform selector
3. 3

   Name the agent and generate the API key

   Type a clear hostname (e.g. "prod-web-01"). Click "Generate API key" — a workspace-scoped key appears below. Copy it now; it is only shown once. This key authenticates the agent when it connects.

   WhereWizard → Name + Generate API key + Copy

   Tip

   Store the key in a secret manager or your config-management vault — do NOT commit it to git.

4. 4

   Copy the install command and run it on the host

   The wizard shows a single curl command that downloads the agent binary, installs the systemd service, and creates the default config file. SSH into your host, paste the command, and run it as root. It finishes in under a minute on most systems.

   WhereWizard → Install command (Copy)
5. 5

   Paste the API key into the agent config

   After install, edit the config file (the wizard tells you the exact path — usually /etc/appstatus/agent.yaml). Paste the API key into the workspace_api_key field. Save the file and restart the agent service so it picks up the new key.

   WhereOn the host → /etc/appstatus/agent.yaml → workspace_api_key
6. 6

   Enable the collectors you want

   The default config enables System, Process and Logs. To capture more, flip on additional collectors in the config (see the options table below for what each one does). Most teams enable System, Process, Logs, Docker and Security in production.

   WhereConfig → collectors section → enabled: true per collector
7. 7

   Watch the agent come online

   Back in the AppStatus UI, refresh the Agents page. Within 60 seconds your host appears with a green status dot. Click the row to open the detail page — CPU, memory, disk, network and process graphs start filling in.

   WhereSidebar → Agents → click your host
8. 8

   (Kubernetes) Use the Helm install instead

   For Kubernetes the wizard shows a Helm install command instead. It deploys the agent as a DaemonSet — one pod per node — with the right RBAC, ConfigMap and Secret automatically. Within a minute every node shows in the Agents list.

   WhereWizard → Platform: Kubernetes → Helm command

Configuration Options

Every option you can set, what each choice means, and what to pick. Use this as a reference while you fill in the form.

Feature Reference

Every feature, where to find it in the app, and what it does. Use this when you know what you want to do but not where it lives.

Next Steps

After the Agent is installed: