---
title: Nodes and fleet
description: Running ClawMetry across several machines — node identity, naming, the fleet view, node caps, and the two identities a browser can hold.
keywords: multi node agent monitoring, agent fleet dashboard, node identity, agent fleet management
eyebrow: Cloud & fleet
---

# Nodes and fleet

A node is one machine running the ClawMetry daemon. The fleet view is every
connected node in one place.

## Node identity

A node has an id, set at connect time and defaulting to the hostname:

```bash
clawmetry connect --key cm_xxx --node-id build-runner-07
```

The default is fine on a laptop and useless on a fleet of identically-named
containers. Set something you would recognise in a list, because that is the
only place you will see it.

```bash
clawmetry status --json | jq '{node_id, endpoint, last_push}'
```

:::note Specs versus addresses
A node's *identity* — what it is — is separate from its *addresses* — where it
can be reached. Renaming a node does not move it, and a node that changed IP is
still the same node. Keep the id stable across rebuilds if you want its history
to stay attached to it.
:::

## The fleet view

Per node: what runtimes it runs, its spend, its health, whether it is online,
and any open Guard incidents.

```bash
curl -s localhost:8900/api/nodes | jq
curl -s localhost:8900/api/nodes/<node_id> | jq
curl -s 'localhost:8900/api/nodes/<node_id>/metrics' -X POST -d '{}' -H 'content-type: application/json' | jq
```

Offline is *derived* rather than reported: a node that has stopped pushing is
offline. It cannot tell you it went away, because a machine that lost power does
not get to send a goodbye.

## Node caps

| Tier | Nodes |
|---|---|
| OSS / Free | 1 |
| Starter and above | Unlimited |

```bash
clawmetry nodes
clawmetry nodes --why 5     # what tier 5 nodes needs
```

The nodes axis is capacity-scoped, so `--why` takes a count.

## Per-node configuration

Nodes are independent. Each has its own store, its own detectors and its own
policies, and each decides for itself whether enforcement is on:

```bash
# on a production node
export CLAWMETRY_POLICY_ENFORCE=1

# on a developer laptop, leave it unset
```

That is deliberate. A policy that should kill a runaway on a build runner should
not be killing someone's interactive session on their laptop, and making
enforcement per-node rather than per-account is what keeps those separate.

## Provisioning a fleet

```bash
#!/usr/bin/env bash
set -euo pipefail
pip install --quiet clawmetry
clawmetry connect \
  --key "$CLAWMETRY_KEY" \
  --enc-key "$CLAWMETRY_ENC_KEY" \
  --node-id "runner-$(hostname -s)" \
  --no-daemon
# your supervisor runs: python -m clawmetry.sync
```

Passing `--enc-key` explicitly gives every node the same encryption key, so one
browser session can decrypt the whole fleet. Without it each node generates its
own and you would need each key to read each node.

→ [Run it as a service](/docs/config/service/)

## Two identities in one browser

Worth knowing if you are ever confused by a cloud dashboard that shows a header
full of sessions above an empty list:

A browser can hold **two** notions of who you are — a node key held in local
storage, and a sign-in cookie. A view that resolves only one of them will show
data for one identity and nothing for the other. If a cloud page looks
inconsistent with the summary above it, that mismatch is the first thing to
suspect.

## Fleet authentication

For a self-hosted or self-managed fleet:

| Variable | Effect |
|---|---|
| `CLAWMETRY_FLEET_KEY` | Fleet authentication key |
| `CLAWMETRY_FLEET_DB` | Fleet database path |

Also available as `--fleet-api-key` and `--fleet-db` on the dashboard.

## Tier

`fleet` is a Starter-and-above feature.