Automated fleet onboarding

#Overview

The single-server flow in Getting started creates the server in the dashboard first (to get a collector key), then installs the agent with that key. That is a manual step per host.

For a fleet, enroll collapses those two steps into one command that runs on the host itself. You bake a single write-scoped account key (gmk_acct_live_) into your automation. Each host runs enroll once; the command registers the server with the Dashboard, receives that server's own collector key (gmk_cru_live_), writes the agent config, and starts the service.

#How enroll works

A single enroll run does four things on the host:

1. Derives a stable machine ID. It reads the DMI product UUID (/sys/class/dmi/id/product_uuid), falling back to /etc/machine-id where DMI is unavailable (many VMs and containers). This ID is the host's durable identity.
2. Registers the server. It calls the Dashboard with your account key, creating a server keyed by that machine ID (or re-attaching to the existing one), and applies any --tags.
3. Writes only the collector key. The Dashboard returns a per-server collector key (gmk_cru_live_). enroll writes that key (and only that key) to /etc/glassmkr/crucible.yaml (mode 0600), then installs and starts the glassmkr-crucible systemd unit, the same on-disk result as glassmkr-crucible init.
4. Discards the account key. The account key is used for the one registration call and is never written to disk. See Where the keys live.

By default enroll verifies connectivity to the Dashboard after registering (the same check init runs). Pass --no-verify to skip that round-trip so the command returns immediately; the agent still verifies on its first snapshot a minute later. That is the right choice inside a boot sequence, where the network may not be fully up yet (see cloud-init).

#Prerequisites

• A write-scoped account key (gmk_acct_live_), minted once. See Programmatic API for how to create one (it needs a step-up password re-auth). Store it in your automation's secret store, not in a machine image.
• Crucible 0.13.21 or later on the host (the release that introduced enroll). Installed globally with npm install -g @glassmkr/crucible, which needs Node.js 24+.
• Outbound HTTPS on port 443 to app.glassmkr.com. No inbound ports.
• Node-quota headroom: each enrolled host consumes one node against your plan quota (3 on Free, your subscribed count on Pro).

#Ansible

Install the agent, then enroll. The creates: guard makes the enroll task a no-op on hosts that already have /etc/glassmkr/crucible.yaml, so re-running the playbook is safe and cheap.

- name: Install the Crucible agent globally
  community.general.npm:
    name: "@glassmkr/crucible"
    global: true
    state: present

- name: Enroll this host into Glassmkr (idempotent)
  ansible.builtin.command:
    cmd: glassmkr-crucible enroll --account-key "{{ vault_glassmkr_account_key }}" --tags "{{ group_names | join(',') }}"
  args:
    creates: /etc/glassmkr/crucible.yaml
  no_log: true

• vault_glassmkr_account_key is your gmk_acct_live_ key, held in Ansible Vault. It is passed for the single registration call and never written to a file on the host.
• group_names | join(',') tags each host with the inventory groups it belongs to, so the dashboard grouping mirrors your inventory.
• no_log: true keeps the key out of Ansible's task output and logs.

#cloud-init

Enroll from runcmd so a host registers itself the first time it boots:

#cloud-config
runcmd:
  - npm install -g @glassmkr/crucible
  - glassmkr-crucible enroll --account-key "gmk_acct_live_..." --no-verify

--no-verify keeps enrollment from blocking on a Dashboard round-trip while the network is still coming up during boot. The agent verifies on its first push.

The npm install line assumes Node.js 24+ is already on the image. If it is not, install it first (a preceding runcmd step, or a base image with Node bundled). And treat cloud-init user-data as sensitive: it often stays readable via the instance metadata service, so pull the account key from a secret manager in runcmd rather than hardcoding it wherever your platform supports that.

#Post-install one-liner

Drop this at the end of any post-install, kickstart, preseed, or provisioning script:

sudo npm install -g @glassmkr/crucible && \
  sudo glassmkr-crucible enroll --account-key "gmk_acct_live_..." --tags "prod,web"

Same effect as the Ansible and cloud-init flows: install the agent, self-register by machine ID, write the collector key, and start the service.

#Idempotent by machine ID

Because the server is keyed by the host's stable machine ID, running enroll more than once is safe:

• Re-runs re-attach, they do not duplicate. A second enroll on an already-enrolled host maps back to the same server record. With the Ansible creates: guard, the command is skipped outright once /etc/glassmkr/crucible.yaml exists.
• Re-images map back to the same server. Rebuild or re-image a host that keeps the same machine identity and it re-attaches to its existing server, preserving history and alert state instead of creating a new node (and consuming another quota slot).
• Keep machine identity unique per host. Hosts that share a machine ID would collapse onto one server record. When you clone from a golden image, make sure each instance gets a distinct identity: regenerate /etc/machine-id on first boot (cloud-init does this by default) so hosts with no distinct DMI UUID do not collide.

#Where the keys live

The security property of enroll is that the powerful credential never touches the host disk. Only a narrowly-scoped, per-host credential does.

So a compromised host leaks only its own collector key, scoped to that one server's telemetry, not the account key that can enroll the rest of your fleet. If a collector key is exposed, rotate it with POST /api/v1/servers/{id}/rotate-key; if the account key is exposed, revoke it from Settings or DELETE /api/v1/account/keys/{id}.

Last updated: 2026-07-14. enroll was introduced in Crucible 0.13.21.

#Next steps

• Getting started: the single-server flow, and the two kinds of keys explained.
• Programmatic API: the raw endpoints behind enroll, plus a 50-server provisioning loop, rate limits, and the audit log.
• Configuration reference: everything you can set in /etc/glassmkr/crucible.yaml.
• Alert rules: the 65 rules the Dashboard evaluates on every snapshot.