---
title: sync
description: The ClawMetry sync daemon — what it does on each cycle, how to start and restart it safely, running it in the foreground, and the environment that tunes it.
keywords: clawmetry sync daemon, agent telemetry ingestion, clawmetry restart daemon
eyebrow: CLI reference
---

# `clawmetry sync`

Start the sync daemon. This is the process that does the actual work: it reads
every runtime, writes the store, runs the detectors, evaluates Guard policies
and — if connected — pushes the encrypted snapshot.

```bash
clawmetry sync
```

| Flag | Effect |
|---|---|
| `--foreground` | Run in the foreground instead of detaching |
| `--restart` | Restart the running daemon — bounces launchd/systemd cleanly, no `SIGKILL` |

## Why it matters more than the dashboard

The dashboard reads through the daemon. If the daemon is not running, every page
is empty — not stale, empty. When something looks wrong, this is the first
process to check.

```bash
clawmetry status
```

## What a cycle does

1. Walk each detected runtime and read what is new since the last high-water
   mark.
2. Normalise into the unified event schema and write to DuckDB. Deterministic
   event ids make a replay a no-op rather than a duplicate.
3. Update the rollups the dashboard reads — per session, per runtime per day,
   per model per day.
4. Run the [detectors](/docs/guard/detectors/) over recent sessions.
5. Evaluate [Guard policies](/docs/guard/policies/), and act if all three locks
   are open.
6. If cloud sync is on, build, encrypt and push the snapshot.
7. Serve the localhost query server the whole time, so readers never block.

## Restarting

```bash
clawmetry sync --restart
```

This is the safe form. It bounces the supervised service rather than sending a
kill signal, so the daemon closes its DuckDB handle cleanly. An abrupt kill
mid-write is how a store ends up needing recovery.

## Foreground

```bash
clawmetry sync --foreground
```

Use it when debugging (`DEBUG=1 clawmetry sync --foreground` is the pairing you
want), or when a supervisor expects to own the process.

## Tuning

| Variable | Default | Effect |
|---|---|---|
| `CLAWMETRY_FAMILY_SESSION_LIMIT` | `50` | Recent sessions ingested per runtime per pass. Raise for deeper backfill. |
| `CLAWMETRY_FAMILY_EVENT_CAP` | — | Events pulled per session, so one huge session cannot starve a cycle |
| `CLAWMETRY_LOCAL_FLUSH_SECS` | — | How often buffered events are flushed to DuckDB |
| `CLAWMETRY_LOCAL_FLUSH_BATCH` | — | Batch size for that flush |
| `CLAWMETRY_LOCAL_MAX_GB` | — | Soft cap on store size |
| `CLAWMETRY_DUCKDB_MEMORY_LIMIT` | — | DuckDB memory limit |
| `CLAWMETRY_DUCKDB_THREADS` | — | DuckDB thread count |
| `CLAWMETRY_DETECTORS` | `1` | Run trajectory detectors |
| `CLAWMETRY_GUARD_POLICIES` | `1` | Evaluate Guard policies at all |
| `CLAWMETRY_POLICY_ENFORCE` | `0` | Let a policy actually signal a process |

:::note Backfilling deeper history
Raising `CLAWMETRY_FAMILY_SESSION_LIMIT` picks up older sessions on the next
cycle, but the daemon tracks a high-water mark per source. If a backfill does
not appear, restart the daemon after raising the limit — a cycle that already
decided it was caught up will not revisit ground it marked done.
:::

## Running it yourself

The daemon is also `python -m clawmetry.sync`, which is the form to put in a
supervisord program or systemd unit. See
[Run it as a service](/docs/config/service/).

## On a memory-constrained machine

DuckDB's performance is sensitive to memory pressure from *other* processes, not
just its own. A machine that is swapping will make the store look slow when the
store is fine. Check actual memory pressure before tuning DuckDB.