Agents & fleet

Agents are organised into groups. A group has a name, a slug, a set of inputs (syslog listener, journald reader, Kafka consumer, …) and a monotonically increasing config_version. Every host that enrols into a group receives the same Vector configuration — that's the unit of fleet-wide change.

The agent runs on Linux (systemd) and Kubernetes (DaemonSet). For a Linux host, the install one-liner downloads the binary, verifies the SHA-256, installs a systemd unit, and waits for an enrolment token to start the agent:

curl -fsSL https://get.logpulse.io | sudo sh

Pin a specific release by setting LOGPULSE_VERSION before piping:

curl -fsSL https://get.logpulse.io | sudo LOGPULSE_VERSION=v0.1.0 sh

The installer creates these paths:

In the dashboard, open Sources → Agents → Groups, pick a group, and click Mint enrolment token. The token (prefix EBT_) is shown once — copy it, then run on the host:

sudo logpulse-agent enrol \
  --api-url https://api.logpulse.io \
  --token EBT_<bootstrap-token>

The agent posts its hostname, platform, and version to LogPulse and receives back a long-lived AGT_ token. The bootstrap token is consumed (one of n uses); the agent token is written to /etc/logpulse-agent/agent-token and used for every subsequent request. From there the agent runs autonomously — start it with systemctl enable --now logpulse-agent.

Every edit to a group (add/edit/delete an input, change routing overrides, rename the group) increments the group's config_version. Agents only re-fetch the config when their own applied_config_version falls behind — see Config polling below. The version is exposed in the dashboard so operators can verify rollout: an agent that still reports an old applied_config_version hasn't yet picked up the latest changes.

Called once during install. Request body authenticates with the short-lived enrolment (bootstrap) token; response includes the agent's long-lived bearer token.

{
  "bootstrapToken": "EBT_<bootstrap-token>",
  "hostname": "fw1.prod.example.com",
  "platform": "linux",
  "os": "Ubuntu 24.04",
  "kernel": "6.8.0-35-generic",
  "agentVersion": "0.4.1",
  "vectorVersion": "0.40.0",
  "groupSlug": "wakanda-enterprise"   // optional: overrides the token's default group
}

The response carries an AGT_ bearer token — shown once, stored hashed (SHA-256) at rest:

{
  "data": {
    "agentId": "f1c4…",
    "agentToken": "AGT_<32-byte base64url>",
    "groupId": "6d0e…",
    "configVersion": 7
  }
}

The agent polls this endpoint at a short interval (~10s by default). It passes its currently applied version via the since query parameter; LogPulse short-circuits with 204 No Content when nothing has changed.

Authorization: Bearer AGT_<token>

→ 204 No Content      # since >= group.configVersion, nothing to apply
→ 200 OK              # new config available
  Content-Type: application/yaml
  x-config-version: 8
  x-config-etag: sha256:9f8…
  Body: <Vector YAML>

The body is the same YAML the dashboard renders under YAML preview on the group page. Agents write it to /var/lib/logpulse-agent/vector.yaml, validate it with vector validate, and reload Vector on success. A failed validation aborts the apply — the agent keeps running the previous config and surfaces the error in its next heartbeat.

When the group has no enabled inputs the response body is the literal string {}. The agent detects this and stops Vector entirely (no placeholder pipeline, no wasted RAM).

Heartbeats are how an agent says "I'm alive", reports its current state, and asks for queued actions. The default cadence is 30 seconds. The body is small but carries every field the dashboard needs to render the agents table:

{
  "agentVersion": "0.4.1",
  "vectorVersion": "0.40.0",
  "appliedConfigVersion": 8,
  "vectorRunning": true,
  "vectorUptimeSeconds": 1837,
  "actionResults": [          // optional — results for previously dispatched actions
    { "actionId": "...", "status": "done", "result": { "previousVersion": "0.4.0" } }
  ]
}

The server updates these columns on agent_registrations:

An agent is considered offline when its last_heartbeat_at is older than the constant AGENT_OFFLINE_THRESHOLD_MS = 5 minutes (defined in packages/types). The dashboard renders an "Offline" badge accordingly.

The response carries any queued actions for this agent — see below.

{
  "data": {
    "pendingActions": [
      {
        "id": "...",
        "type": "upgrade_agent",
        "payload": { "targetVersion": "0.4.2" }
      }
    ]
  }
}

Actions are a generic queue for "do something on the agent" instructions. The current type is upgrade_agent; future types (restart Vector, drop cache, rotate token) plug into the same machinery. Status flows in one direction only:

The server validates state transitions: an action that's already done can't go back to running; an expired action stays expired. Agents only receive non-expired, non-cancelled actions in the pendingActions array (up to 10 per heartbeat).

The bearer token was revoked from the Agents tab, or it doesn't match the prefix on the server side. Mint a fresh bootstrap token, run logpulse-agent enrol again, and restart the unit.

Check the agent's row in the dashboard. If applied_config_version stays behind config_version after a couple of polls, the agent likely failed validation — open the agent logs (journalctl -u logpulse-agent) and look for vector validate errors. The agent keeps the previous config running until a new one passes validation.

The agent hasn't sent a heartbeat in over 5 minutes. Common causes: outbound HTTPS to api.logpulse.io is blocked by a firewall, the agent process crashed (systemctl status logpulse-agent), or system clock skew is rejecting TLS. The dashboard tooltip on the Offline badge shows the exact last seen timestamp.

The upgrade started but never reported a result. Check the agent's agent_version in the next heartbeat — if it matches the target, the upgrade succeeded but the result-reporting heartbeat got lost; the action will expire by itself. If the version is unchanged, look at the install script's output in /var/log/logpulse-agent/upgrade.log.