enroll

Reference for linuxguard-agent enroll — bind a host to a tenant using a long-lived API key, with environment / tag assignment and mTLS certificate provisioning.

Synopsis

Bind a host to a LinuxGuard tenant using a long-lived API key. enroll writes the tenant identity to the local config database, requests an mTLS client certificate from the backend (when the tenant has a CA provisioned), and sends an initial snapshot so the host appears in the console without waiting for the first scheduled heartbeat. Once enrolled, start reuses the persisted credentials and the host operates in typical service mode.

The alternative enrollment path — short-lived TOTP tokens for ephemeral / containerised deployments — does NOT use this command. See start § Enrollment flags for the TOTP path, which fires the enrol POST from inside start rather than from a separate subcommand.

linuxguard-agent enroll --api-key <key> --tenant-id <uuid> [flags]

Flags

Flag	Type	Required	Default	Description
--api-key <key>	string	yes	—	Long-lived API key issued from the LinuxGuard console (Settings → API Keys). Authenticates the enrol POST and is persisted as cfg.ApiKey for subsequent heartbeats.
--tenant-id <uuid>	string	yes	—	Tenant UUID the host enrols into. Persisted as cfg.TenantID. Must match the API key's owning tenant — mismatch produces a backend rejection.
--environment <name>	string	no	—	Logical environment name (e.g., production, staging, development). Persisted as cfg.Environment and surfaced in console filters. Has one backward-compatible alias: --group (v3.0 vocabulary).
--tag <name>	string slice	no	—	Tag name applied to the host's identity. Repeat the flag to assign multiple tags (--tag web --tag us-east). Persisted as cfg.Tags.

If the host is already enrolled (cfg.ServerID != ""), enroll is a no-op: it prints the existing server ID and the RegisteredAt timestamp and exits 0 without contacting the backend.

Environment

enroll reads no LINUXGUARD_* environment variables of its own. Channel-baked defaults govern the enrollment URL: stable builds POST to https://api.linuxguard.io/v1/agent/enroll, every other channel POSTs to https://dev-api.linuxguard.io/v1/agent/enroll. Override the URL out-of-band by rebuilding the agent against a different channel — there is no user-facing override flag.

The persisted enrollment is stored in the agent's local config database under /var/lib/linuxguard/ on Linux hosts. start reads the same database to recover the tenant identity, API key, base URL, and server ID at boot.

Signals

enroll is a one-shot CLI invocation — it does not install signal handlers via signal.Notify. Ctrl-C aborts the enrol POST or the initial-snapshot POST via Go's default SIGINT handler; an aborted enrol mid-flight does NOT roll back partial config writes (the cfg.ApiKey / cfg.TenantID / cfg.BaseURL fields are persisted BEFORE the API client is reconfigured).

Exit codes

Code	Meaning
0	Enrolment succeeded (mTLS certificate stored if the tenant has a CA; initial snapshot sent or warned non-fatally). Or: the host was already enrolled and the no-op path printed the existing identity.
1	General error — surfaced via log.Fatal after the agent run returns a non-nil error. Includes: config-service init failure, persist failure for the pre-enrol config write, network failure for the enrol POST, backend rejection (HTTP 4xx/5xx — including "tenantId required" or "API key invalid"), nil enrollment response, or post-enrol config-save verification mismatch.
2	Argument parsing error — missing one of the required flags --api-key or --tenant-id, or unknown flag passed on the command line.

Examples

Enrol a host into production

sudo linuxguard-agent enroll \
  --api-key 4f8c1e9d-...-7a2b \
  --tenant-id 11111111-2222-3333-4444-555555555555 \
  --environment production \
  --tag web-server --tag us-east-1

Expected stdout (truncated):

>> mTLS client certificate stored successfully
>> Sending initial snapshot...
>> Initial snapshot sent successfully
>> Successfully enrolled to LinuxGuard Endpoint: https://api.linuxguard.io/v1/

After the command returns, start the agent service:

sudo systemctl enable --now linuxguard-agent

Re-running enrol on an already-enrolled host

sudo linuxguard-agent enroll --api-key X --tenant-id Y

Stdout:

This server has been enrolled since Mon, 31 May 2026 12:34:56 UTC

Exit code: 0. The flags are accepted but ignored — cfg.ServerID is non-empty so the enrol POST is short-circuited. To re-enrol the host into a different tenant, run linuxguard-agent unenroll first.

Enrol via the backward-compatible --group alias

sudo linuxguard-agent enroll \
  --api-key X --tenant-id Y \
  --group staging

Equivalent to --environment staging. Preserved for v3.0 deployment scripts; new automation should use --environment directly. Both forms persist to the same cfg.Environment field.

Handling the initial-snapshot warning

If the enrol POST succeeds but the initial-snapshot POST fails (e.g., the host took longer than the snapshot collector's timeout), stdout shows:

>> Warning: Initial snapshot failed (...), will retry on agent start
>> Successfully enrolled to LinuxGuard Endpoint: ...

Exit code: 0. The enrolment is complete; the snapshot will be retried at the next linuxguard-agent start. No operator action is required.

---

Related: start | unenroll | show-config | CLI Reference