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}'

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

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.

Edit this page View as Markdown Report an issue