Skip to main content

Install the Constellation Fleet Agent

The Fleet Agent accepts telemetry from applications on a local Unix socket, buffers it, and delivers it to Constellation. The installer requires a Constellation API token; the host requires outbound network access to Constellation.

Applications write to the local Unix socket; the agent buffers records and forwards them to Constellation ingest.

Requirements​

  • A 64-bit Linux host using systemd
  • An amd64 or arm64 processor
  • Root access
  • Outbound HTTPS and gRPC access to Constellation
  • Pro or Enterprise Fleet SDK access, with ingestion enabled
  • A Constellation API token with telemetry:write and topology:read

Export the token without putting it in a command argument:

export CONSTELLATION_API_TOKEN='<your token>'

Install the default gRPC agent:

curl -fsSL https://install.constellation.space/agent | \
  sudo env CONSTELLATION_API_TOKEN="$CONSTELLATION_API_TOKEN" sh

Expected final output:

constellation-agent install: READY
constellation-agent install: verify: sudo constellation-agent verify
constellation-agent install: logs:   sudo constellation-agent logs

The installer verifies downloaded artifacts, writes the credential to /etc/constellation/agent.env with file mode 0600, installs the systemd service, and creates /run/constellation-agent/telemetry.sock.

Confirm the service is running:

sudo constellation-agent status

Grant an application access​

Create a dedicated publisher account if needed, then add it to the socket group:

id constellation-publisher >/dev/null 2>&1 || \
  sudo useradd --system --no-create-home --shell /usr/sbin/nologin constellation-publisher
sudo usermod -aG constellation constellation-publisher

Start or restart constellation-publisher.service after changing group membership. The group grants socket access only; it cannot read the Fleet Agent credential.

Next: Send one metric.