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

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:

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:

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

Access#

Keep the dashboard on loopback. It is the default. → Ports and networking

Use API tokens for anything programmatic:

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.

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

Integrity#

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

Posture#

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#

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

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.