ContextQMD
Back to Netdata

`.env` setup and reference

.agents/ENV.md

2.11.08.7 KB
Original Source

.env setup and reference

.env at the repo root holds per-user secrets and pointers that AI-skill scripts consume. It is gitignored -- values never reach the committed history.

This file is the single setup guide. Every skill that needs .env keys lists them here with the role, where to find the value, sample format, and which scripts consume it. If a script tells you a key is missing, check this file.

Quick start

bash
cd <repo>
cp .env.template .env
# Open .env in your editor and fill in the keys you need.
chmod 0600 .env   # optional but recommended

You only need to fill in keys for the skills you actually use. Each script checks its own required keys and exits with a clear error if any are missing -- it will not corrupt state if you forget a key.

Key reference

Netdata Cloud + agents

KeyRoleWhere to find itSample format
NETDATA_CLOUD_TOKENlong-lived Cloud REST tokenapp.netdata.cloud -> user menu -> Settings -> API Tokens -> Create. scope:all (full) or scope:grafana-plugin (read-only data).36-char UUID-shaped token
NETDATA_CLOUD_HOSTNAMECloud REST API hostAlmost always app.netdata.cloudapp.netdata.cloud
NETDATA_REPOS_DIRlocal Netdata-org repos mirror dirPick or create. Will be populated by mirror-netdata-repos skill's sync script.$HOME/src/netdata

Netdata Cloud claiming (build-MCP auto-claim)

Used by the build/run MCP server under packaging/tools/automation/mcp. When NETDATA_CLAIM_TOKEN is set in that server's environment, every agent it launches claims itself to Cloud as an ephemeral node named mcp-<agent_id>. Leave the token blank to launch unclaimed (local + MCP access still work).

KeyRoleWhere to find itSample format
NETDATA_CLAIM_TOKENSpace claim token; enables auto-claim when setapp.netdata.cloud -> Space settings -> Connect Nodes -> the --claim-token valuelong opaque token
NETDATA_CLAIM_ROOMScomma-separated Room id(s) for the node (optional)same Connect Nodes dialog -> the --claim-rooms valueUUID[,UUID...]
NETDATA_CLAIM_URLCloud base URL (optional)defaults to https://app.netdata.cloud agent-sideURL

agent-events ingestion node

The agent-events node is the Netdata-operated ingestion host that receives status submissions from every Netdata agent in the wild. The query-agent-events skill triages crashes / panics / fatals from it.

KeyRoleWhere to find itSample format
AGENT_EVENTS_HOSTNAMENetwork address of the ingestion node. Dual-duty -- ssh host (ssh ${AGENT_EVENTS_HOSTNAME}) AND direct-HTTP host (http://${AGENT_EVENTS_HOSTNAME}:19999/). Can be a DNS name or an IP. NOTE -- this is NOT the journalctl namespace (which is hardcoded to agent-events) and NOT the Cloud room name (also hardcoded to agent-events).Operations / your records10.20.1.105 or agent-events.example
AGENT_EVENTS_NODE_IDCloud node UUID for that nodeVisit the node in app.netdata.cloud and copy the UUID from the URL; or list nodes via the Cloud API and pick the matching one.UUID
AGENT_EVENTS_MACHINE_GUIDNetdata machine GUID for that nodeOn the host: sudo cat /var/lib/netdata/registry/netdata.public.unique.idUUID

Coverity Scan (coverity-audit skill)

KeyRoleWhere to find itSample format
COVERITY_HOSTScan API hostAlways https://scan4.scan.coverity.com for the new instanceURL
COVERITY_PROJECT_IDinteger project idURL query param ?projectId=... when you click the project in the dashboardsmall integer
COVERITY_COOKIEfull browser Cookie header (with XSRF-TOKEN)DevTools -> Network -> any request to scan4 -> Request Headers -> Cookielong Cookie string
COVERITY_VIEW_OUTSTANDINGinteger viewId for the "Outstanding" viewURL query param ?viewId=... when you open that viewsmall integer

The cookie expires; refresh by re-pasting from the browser (or run coverity-audit/scripts/keepalive.sh to extend it during a triage session).

SonarCloud (sonarqube-audit skill)

KeyRoleWhere to find itSample format
SONAR_HOST_URLSonarCloud hostAlways https://sonarcloud.ioURL
SONAR_ORGyour organization key on SonarCloudsonarcloud.io organization pageshort string
SONAR_PROJECTprojectKey on SonarCloudFor Netdata: netdata_netdataorg_repo form
SONAR_TOKENpersonal access tokenhttps://sonarcloud.io/account/security -> Generatelong opaque token

Codacy Cloud (codacy-audit skill)

KeyRoleWhere to find itSample format
CODACY_TOKENAccount API token (header api-token: <value>)https://app.codacy.com -> top-right avatar -> Account -> API tokens -> "Create API Token"20-char opaque string
CODACY_HOSTAPI host. Defaults to https://api.codacy.com; set only if Codacy moves the API host.n/aURL
CODACY_PROVIDERgit provider. Defaults to gh (GitHub).n/agh
CODACY_ORGCodacy organization (matches the GitHub org). Defaults to netdata.n/ashort string
CODACY_REPOCodacy repository name. Defaults to netdata.n/ashort string

CODACY_TOKEN is required by pr-issues.sh and any wrapper that calls the v3 API. analyze-local.sh does NOT need it (the local CLI runs anonymously).

Per-skill checklist

Set the keys for whichever skills you plan to use. Skills not listed here either need no .env keys or rely on gh auth instead.

query-netdata-cloud / query-netdata-agents

  • NETDATA_CLOUD_TOKEN
  • NETDATA_CLOUD_HOSTNAME
  • (For agent-events examples in those skills' docs: AGENT_EVENTS_HOSTNAME, AGENT_EVENTS_NODE_ID, AGENT_EVENTS_MACHINE_GUID.)

query-agent-events

  • NETDATA_CLOUD_TOKEN
  • NETDATA_CLOUD_HOSTNAME
  • AGENT_EVENTS_HOSTNAME
  • AGENT_EVENTS_NODE_ID
  • AGENT_EVENTS_MACHINE_GUID

mirror-netdata-repos

  • NETDATA_REPOS_DIR

integrations-lifecycle / learn-site-structure

  • NETDATA_REPOS_DIR (for cross-repo path references in examples / recipes)

coverity-audit

  • COVERITY_HOST
  • COVERITY_PROJECT_ID
  • COVERITY_COOKIE
  • COVERITY_VIEW_OUTSTANDING

sonarqube-audit

  • SONAR_HOST_URL
  • SONAR_ORG
  • SONAR_PROJECT
  • SONAR_TOKEN

codacy-audit

  • CODACY_TOKEN (required by pr-issues.sh; not by analyze-local.sh)
  • CODACY_HOST (optional; defaults to https://api.codacy.com)
  • CODACY_PROVIDER / CODACY_ORG / CODACY_REPO (optional; default to gh / netdata / netdata)

pr-reviews / graphql-audit

  • No .env keys required. Both rely on gh auth login having been run.

Common mistakes

  • Trailing whitespace in a value: bash variable expansion preserves the whitespace; the value comes through with the trailing space and breaks API calls silently. Strip whitespace inside the quotes.
  • Wrong quoting: quotes around bash-expansion characters ($, backticks, \) are interpreted. For tokens containing those characters, use single quotes: SONAR_TOKEN='abc$def'.
  • Expired Coverity cookie: re-paste from the browser. The script's error message will tell you when this happens.
  • Wrong gh org: pr-reviews and graphql-audit use gh against the current repo's remote. Make sure your remote points to the right repo (git remote -v).
  • Cloud token scope too narrow: some endpoints require scope:all. If you get a 403 with what looks like a valid token, regenerate with broader scope.
  • NETDATA_REPOS_DIR and tilde: bash does NOT expand the home-directory shortcut character inside double-quoted strings. If you write "<TILDE>/src/netdata", the literal tilde is kept in the value, and scripts will fail with "directory does not exist" because that path is not real. Use $HOME instead, or the full absolute path: 
    NETDATA_REPOS_DIR="$HOME/src/netdata"

Why these are env-keyed

Every value above is either:

  • a secret (token / cookie) that must never leak into committed artifacts, or
  • a per-user / per-deployment path or identifier (mirror dir, ingestion node) that varies between contributors.

The committed skills, scripts, and docs reference these values exclusively via ${KEY} placeholders, never literal values. The discipline is enforced by the spec at <repo>/.agents/sensitive-data-discipline.md, which includes a pre-commit grep recipe to catch literal-value leaks.

When a skill says "X is empty in .env"

That skill's _lib.sh ran the bash safety net : "${X:?...}" because X was unset or empty. Open this file, find the row for X, follow the "where to find it" pointer, paste the value into .env, and re-run.