---
title: Hardening
description: Running ClawMetry safely — the read-only contract, redaction, credential scanning, what the store contains, the intervention surfaces and a hardening checklist.
keywords: agent observability security, redact secrets telemetry, agent security posture, clawmetry hardening
eyebrow: Configuration
---

# Hardening

## The threat model, plainly

**ClawMetry's store contains your agents' transcripts.** That includes source
code, API responses, file contents and any secret that ended up in a prompt or a
tool result. Anyone who can read the store or reach the dashboard can read all
of it.

**ClawMetry can signal processes.** Four surfaces, all documented, all off or
gated by default. → [Guard](/docs/guard/overview/)

**ClawMetry reads your agent directories.** Read-only, always, with no exception
— but it does read them.

Everything below follows from those three facts.

## Redaction

On by default:

```bash
export CLAWMETRY_REDACT=1     # the default
export CLAWMETRY_REDACT=0     # raw capture, opt out deliberately
```

Redaction masks secret-shaped values before they are stored. It is pattern-based
and therefore not complete: a token that does not look like a token gets
through. Treat it as reducing exposure, not eliminating it.

## Credential scanning

The other direction — finding secrets your agents *accessed*:

```bash
curl -s localhost:8900/api/security/credential-scan | jq
```

Guard's `credential_access` detector flags sessions that read credential-shaped
paths, with benign shapes excluded explicitly (`.env.example`, `.env.sample`,
`.env.template`, `.pub`). An agent reading `.env.example` is doing its job; an
agent reading `.env` and then making network calls is a different session.

→ [Detectors](/docs/guard/detectors/)

## Access

**Keep the dashboard on loopback.** It is the default.
→ [Ports and networking](/docs/config/networking/)

**Use API tokens** for anything programmatic:

```bash
export CLAWMETRY_API_TOKENS=<token-a>
```

**Put a reverse proxy in front** if you need remote access, with real
authentication. Do not rely on network position alone.

**Protect the store file.** It is a file with your transcripts in it. Standard
user-only permissions, and think about whether your backup target is somewhere
you want them.

## The intervention surfaces

Four, and no more. Adding a fifth means adding it to this list with locks of the
same strength.

| Surface | Default | Gate |
|---|---|---|
| Manual Pause/Stop/Kill | Available | Origin-checked. Not entitlement-gated: you pressed it. |
| Autonomous policy | **Off** | Three locks: action not `monitor`, `CLAWMETRY_POLICY_ENFORCE=1`, entitlement fails closed |
| Pre-tool gates | Off | Requires a runtime hook and configuration |
| Cron management | Available | Explicit action |

```bash
export CLAWMETRY_POLICY_ENFORCE=0   # the default. Nothing autonomous happens.
export CLAWMETRY_GUARD_POLICIES=0   # do not even evaluate policies
```

## Integrity

```bash
export CLAWMETRY_INTEGRITY=1
clawmetry verify-integrity --json
```

Makes tampering with the event log **evident**. It does not prevent it, and it
does not prove the events were accurate when written.
→ [Tamper-evident integrity](/docs/data/integrity/)

## Posture

```bash
curl -s localhost:8900/api/security/posture | jq
curl -s localhost:8900/api/security/policy-events | jq
curl -s localhost:8900/api/authority-violations | jq
curl -s localhost:8900/api/audit-log | jq
```

Posture grading is honest about what it can verify. A closed-source component is
graded on what is observable from outside rather than assumed compliant, which
means a grade may be lower than a vendor's own claim — deliberately.

`authority-violations` is worth a periodic look: actions an agent took that its
declared permissions did not cover. On a well-configured node it should be
empty.

## Network posture

```bash
export CLAWMETRY_OFFLINE=1        # no outbound calls at all
export CLAWMETRY_AUTO_UPDATE=0    # no update checks
export CLAWMETRY_NO_TELEMETRY=1   # no usage telemetry
export CLAWMETRY_NO_CLOUD=1       # local only
```

With cloud sync on, session content is AES-256-GCM encrypted before it leaves
and the server holds ciphertext it cannot read. What is still visible: that your
node exists, and aggregate counters.
→ [End-to-end encryption](/docs/cloud/encryption/)

## Hooks

ClawMetry writes into a runtime's hook configuration when a pre-tool gate is
registered — the one place it writes outside its own directory. It marks its own
entries and removes only those.

**Never delete a hook you did not create.** That applies to ClawMetry and to
anyone editing by hand.

## A checklist

For a machine that matters:

- [ ] Dashboard bound to `127.0.0.1`, or behind an authenticating proxy
- [ ] `CLAWMETRY_API_TOKENS` set if anything calls the API
- [ ] `CLAWMETRY_REDACT` left at its default of on
- [ ] `CLAWMETRY_INTEGRITY=1`
- [ ] `CLAWMETRY_POLICY_ENFORCE` deliberately set, not accidentally
- [ ] Retention set to what you actually need
- [ ] Store file permissions user-only
- [ ] Backups of the store treated as sensitive
- [ ] Cloud encryption key backed up somewhere it cannot be lost
- [ ] `CLAWMETRY_OFFLINE=1` if the host should not talk to the internet
- [ ] `credential-scan` and `authority-violations` reviewed periodically

## Reporting a vulnerability

Please report security issues privately rather than in a public issue. Public
issue bodies are a disclosure channel, and a report with a reproduction in it
is a working exploit for anyone reading.