Environment variables

If you are integrating against the API directly, you need one credential and one base URL: read the key from a secrets manager or an environment variable and send it as the x-api-key header. That is the whole developer-facing surface.

The variables below configure the fleet agent — the collector you run on a host to ship telemetry.

Fleet agent

The installer writes these to /etc/constellation/agent.env (root-only) and /etc/constellation/socket.env; the collector reads them at start.

Variable	Purpose
CONSTELLATION_API_TOKEN	The account API token, sent as x-api-key
CONSTELLATION_API_URL	Platform API base URL for this host (for example https://api.constellation.space)
CONSTELLATION_ENTITY_ID	Node identity for the agent's OWN health metrics. Optional: the installer falls back to /etc/machine-id, then the hostname, and only fails if neither exists. Set it explicitly on cloned images, where a shared machine-id would merge every node's health into one entity. It is not a global tag — it is scoped to inputs.internal on purpose, so a socket record missing its own entity_id surfaces as misconfigured instead of being silently attributed to the node. Every record you publish needs its own entity_id.
CONSTELLATION_ENDPOINT	gRPC ingest host:port for gRPC egress. Empty on HTTP egress
CONSTELLATION_SOCKET_PATH	Ingest socket. Default /run/constellation-agent/telemetry.sock

Publishing applications read CONSTELLATION_SOCKET_PATH only. The credential stays in the root-only file and never reaches application code.

Installer

The install script reads these. Set them before piping the script to sh.

Variable	Purpose
CONSTELLATION_API_TOKEN	Required. The data-plane key the collector authenticates with
CONSTELLATION_API_URL	Override the API base URL. Default https://api.constellation.space
CONSTELLATION_EGRESS	grpc or http. Selects native gRPC egress or REST egress. Any other value fails the install. See Choosing an egress mode
CONSTELLATION_BUFFER_STRATEGY	disk (default) or memory. Disk survives a restart and caps ingest near 290 metrics/s; memory is far faster and loses up to one flush interval on a hard stop. Any other value fails the install. See Throughput budget
CONSTELLATION_ENDPOINT	gRPC ingest host:port. Derived from CONSTELLATION_API_URL for the production hostname; required for any other API URL
CONSTELLATION_TELEGRAF_VERSION	Pin a Telegraf version instead of the default
CONSTELLATION_TELEGRAF_PACKAGE	Path to a local .deb or .rpm for private or air-gapped hosts
CONSTELLATION_TELEGRAF_SIGNATURE	Detached signature for that package. Required with a local package
CONSTELLATION_TELEGRAF_SHA256	Override the expected package checksum

Install with a pinned collector version and an explicit egress mode:

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

gRPC egress child

On gRPC egress the collector supervises telegraf-constellation-grpc, which translates line protocol to the native ingest contract. The installer passes it the endpoint and the credential through the collector's environment, so the child never reads a config file and application code still never holds a credential. The remaining variables are tuning knobs you set on the [[outputs.execd]] block if you need them.

Variable	Purpose
CONSTELLATION_ENDPOINT	Required. gRPC host:port. The child exits without it
CONSTELLATION_API_TOKEN	Required. Sent as x-api-key request metadata
CONSTELLATION_TIMEOUT	Per-RPC timeout as a Go duration. Default 10s
CONSTELLATION_BATCH_SIZE	Records per Write call, 1 to 1000. Default 500
CONSTELLATION_INSECURE	true disables TLS. Test and private-tunnel use only; the default is TLS with a 1.2 minimum

Key handling guidance lives in Security overview; the install contract in Fleet agent.