---
title: onboard / setup
description: The ClawMetry first-run wizard — every flag, local-only mode, non-interactive cloud onboarding, and what the wizard actually does.
keywords: clawmetry onboard, clawmetry setup, clawmetry local only, headless install
eyebrow: CLI reference
---

# `clawmetry onboard` / `clawmetry setup`

The first-run wizard. `setup` is the same command framed as "connect to
ClawMetry Cloud"; both accept the same flags and do the same work.

```bash
clawmetry onboard
```

## What it does

1. Detects the agent runtimes on this machine.
2. Asks whether you want a cloud account, or takes the answer from a flag.
3. Writes configuration into `~/.clawmetry/`.
4. Starts the sync daemon and supervises it (launchd, systemd or the platform
   equivalent).
5. Opens the dashboard.

## Flags

| Flag | Effect |
|---|---|
| `--key cm_xxx` | API key, skipping the prompt |
| `--local`, `--no-cloud` | Local only: no cloud account, nothing leaves this machine |
| `--cloud` | Create a cloud account non-interactively, skipping the prompt |
| `--node-id NAME` | Custom node name (default: the hostname) |
| `--foreground` | Run the daemon in the foreground instead of supervising it |

## Local only

```bash
clawmetry onboard --local
```

This writes a persistent local-only marker. A later `clawmetry connect` refuses
to override it unless given `--force`, which exists so an automated provisioning
run cannot quietly opt a machine into cloud sync that somebody deliberately
opted out of.

Everything works in local mode: all {{RUNTIME_COUNT}} runtimes, every dashboard
page, Guard, detectors, the MCP server, the query API. What you give up is the
cloud dashboard, fleet view and phone approvals.

## Non-interactive

For provisioning:

```bash
# local-only node, no prompts at all
clawmetry onboard --local --node-id build-runner-07

# cloud node with a key you already hold
clawmetry onboard --key "$CLAWMETRY_KEY" --node-id build-runner-07 --cloud
```

Both forms are safe to run more than once — a second run reconciles rather than
duplicating.

## Node names

`--node-id` defaults to the hostname, which is fine on a laptop and useless on a
fleet of identically-named containers. Set it to something you would recognise
in a list. Node identity is covered in [Nodes and fleet](/docs/cloud/nodes/).

## Running the daemon yourself

If you supervise processes with something of your own — supervisord, a systemd
unit you manage, a container entrypoint — do not let the wizard install its own
supervision:

```bash
clawmetry connect --key cm_xxx --no-daemon
# then run: python -m clawmetry.sync
```

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

## Troubleshooting the wizard

| Symptom | Cause |
|---|---|
| Hangs at a prompt in CI | Interactive by default — pass `--local` or `--key` |
| "already local-only" on connect | The local marker is set; `--force` overrides it deliberately |
| No runtimes detected | Stores relocated — see [How detection works](/docs/runtimes/detection/) |
| Browser does not open | Set `CLAWMETRY_NO_BROWSER=1` if that is what you want, or open `localhost:8900` yourself |