# Getting started

Register a server, install the Crucible agent, see the first snapshot. About five minutes end to end.

## Overview

Glassmkr has two parts:

- **Dashboard** is the hosted service at [app.glassmkr.com](https://app.glassmkr.com). It stores your data, evaluates alerts, and renders server health.
- **Crucible** is the MIT-licensed agent. It runs on your server, collects health data, and pushes snapshots to the Dashboard.

You register a server in the Dashboard (which gives you a collector key), then install Crucible on that server with the key. That is the entire flow for a single server.

> **Automating, or onboarding many servers?** The whole flow runs over the API, no dashboard clicks. A `write`-scoped account key (`gmk_acct_live_`) creates each server with `POST /api/v1/servers`, and the response returns that server's collector key. See the [Programmatic API quickstart](/docs/programmatic-api).

Last verified: 2026-06-26 against Crucible v0.13.12.

## Prerequisites

- A Linux server (Ubuntu, Debian, RHEL, Rocky, Alma, Arch, or Alpine).
- Root or sudo access.
- Outbound HTTPS (port 443) to `app.glassmkr.com`. No inbound ports required.

## Step 1: Create a Dashboard account

Go to [app.glassmkr.com](https://app.glassmkr.com/#register) and sign up with email, Google, or GitHub. Free accounts can monitor up to 3 servers with 7-day retention.

## Step 2: Register a server

After logging in, click **+ Add Server**. Enter a name (for example, `web-01` or `db-prod`).

The Dashboard generates a **collector key** that starts with `gmk_cru_live_`. This key is shown once. Copy it. Servers created before Crucible 0.9.0 may have a legacy `col_xxx` key; both formats work.

> **What is this key?** The collector key (`gmk_cru_live_xxx`) authenticates snapshot pushes from this specific server to the Dashboard. Each server gets its own key, scoped to that server's telemetry only. This is different from the account API key (`gmk_acct_live_xxx`) in Settings, which is for programmatic API access from automation like Ansible, Terraform, or scripts.

## Step 3: Install Crucible

SSH into your server. The dashboard shows the exact command with your collector key pre-filled. The bootstrap installer is:

```
curl -sf https://glassmkr.com/install.sh | sudo bash -s -- --api-key gmk_cru_live_your_key_here
```

The installer:

- Installs Node.js 24 if not present.
- Installs `smartmontools` (SMART disk monitoring).
- Installs `ipmitool` if available (IPMI hardware monitoring).
- Runs `glassmkr-crucible init` to validate the key against the Dashboard, write `/etc/glassmkr/crucible.yaml` (mode 0600; migrates a pre-0.13.5 `/etc/glassmkr/collector.yaml` in place when present), and install the systemd unit.
- Starts the `glassmkr-crucible` service (runs as the non-root `glassmkr` user).

**Reading the key from a password manager?** Pipe it through stdin:

```
op read "op://Private/Dashboard/key" | sudo glassmkr-crucible init --api-key -
```

The legacy `--dashboard-key` flag is preserved as an alias for `--api-key` so existing Ansible or Terraform automation keeps working without changes.

### npm install

If you would rather not pipe to bash:

```
sudo npm install -g @glassmkr/crucible
sudo glassmkr-crucible init --api-key gmk_cru_live_your_key_here
```

### Docker install

The containerized agent reads its key from `/etc/glassmkr/crucible.yaml` on the host (it does not read a key from the environment), so create the config first, then start the container with it mounted. The image is on [Docker Hub](https://hub.docker.com/r/glassmkr/crucible):

```
# 1. Create the config (replace with your Dashboard key)
sudo mkdir -p /etc/glassmkr
sudo tee /etc/glassmkr/crucible.yaml << 'EOF'
server_name: "web-01"
dashboard:
  enabled: true
  url: "https://app.glassmkr.com"
  api_key: "gmk_cru_live_your_key_here"
EOF

# 2. Run the agent (privileged + host namespaces so it monitors the host, not the container)
docker run -d --restart=unless-stopped --name glassmkr-crucible \
  --pid=host --net=host --privileged \
  -v /etc/glassmkr:/etc/glassmkr:ro \
  docker.io/glassmkr/crucible:latest
```

Run `glassmkr-crucible init --help` to see the full flag list (custom server name, alternate Dashboard URL, etc.).

## Step 4: Verify

Check that Crucible is running:

```
sudo systemctl status glassmkr-crucible
```

You should see `active (running)`. Check the logs for the first collection:

```
sudo journalctl -u glassmkr-crucible --since "5 min ago" --no-pager
```

Expected output (the first collection may take a few seconds longer than later ones):

```
[collector] Starting. Server: web-01. Interval: 60s
[collector] IPMI: enabled, SMART: enabled
[collector] Dashboard: https://app.glassmkr.com
[collector] Collecting...
[collector] Collected in 1013ms. Alerts: 0 active, 0 new, 0 resolved

=== First collection complete ===
Server: web-01 (Ubuntu 24.04 LTS)
CPU:    5.3% (load: 0.14)
RAM:    12.1% (1940 / 16036 MB)
Disk:   23% (/)
SMART:  2 drive(s) checked
Network: eth0, eth1
IPMI:   available
Active alerts: 0
Dashboard: enabled

[dashboard] Push successful. Active alerts: 0
```

Within 60 seconds (one collection interval), the server appears on the [Dashboard](https://app.glassmkr.com) with live data. The Dashboard evaluates all 65 alert rules on each push.

Last verified: 2026-05-22. Default snapshot interval is 60 seconds in Crucible v0.10.0 and later.

## Two kinds of keys

Glassmkr uses two key types:

| Key type | Prefix | Created where | Used by | Purpose |
| --- | --- | --- | --- | --- |
| **Collector key** | `gmk_cru_live_` (legacy: `col_`) | Dashboard: + Add Server | Crucible agent | Authenticates snapshot pushes from one specific server. Scoped to that server; cannot list other servers or read account settings. |
| **Account API key** | `gmk_acct_live_` | Settings: API keys (every plan) | Automation: Ansible, Terraform, scripts, MCP clients | Programmatic access to your account (list servers, query health, mutate state). On every plan, with read, write, or admin scope; bounded by the 3-node quota and rate limits. |

## Next steps

- [Set up notification channels](/docs/channels) (email, Telegram, Slack, Discord, PagerDuty, webhooks) with per-channel priority filtering.
- [Review the 65 alert rules](/docs/rules) grouped across 9 categories.
- [Explore the full configuration reference](/docs/configuration) for thresholds, intervals, and optional collectors.
- [API reference](/docs/api) for programmatic access.