---
title: Self-hosted ingest
description: Running the ClawMetry ingest endpoint yourself — the surface nodes push to, configuration, data residency, and when this is the right deployment.
keywords: self hosted agent observability, air gapped agent monitoring, data residency agent telemetry, on premise agent dashboard
eyebrow: Cloud & fleet
---

# Self-hosted ingest

Run the endpoint yourself. Nodes push to your server instead of the hosted one,
and you own the storage.

```bash
CLAWMETRY_ENDPOINT=https://clawmetry.internal.example.com \
  clawmetry connect --key cm_xxx
```

## When this is the right choice

- **Data residency.** The snapshot must stay in a jurisdiction or a network you
  control.
- **Air-gapped networks.** There is no route to a hosted endpoint at all.
- **Audit perimeter.** Everything must be inside a boundary you can attest to.

If none of those apply, the hosted endpoint with
[end-to-end encryption](/docs/cloud/encryption/) already means the server cannot
read your content — self-hosting is then a matter of operational preference
rather than confidentiality.

## The ingest surface

Nodes push to a small set of endpoints, and your server implements them:

| Endpoint | Payload |
|---|---|
| `POST /auth` | Node authentication |
| `POST /api/register` | Node registration |
| `POST /ingest/heartbeat` | Liveness and top-line counters |
| `POST /ingest/events` | The event stream |
| `POST /ingest/sessions` | Session records |
| `POST /ingest/logs` | Logs |
| `POST /ingest/memory` | Memory file state |
| `POST /ingest/system-snapshot` | Host health |
| `POST /ingest/stream` | Live stream |
| `POST /ingest/autonomy` | Autonomy state |
| `POST /ingest/cache` | Cached query results |

And a read surface for the dashboards you point at it:

| Endpoint | Returns |
|---|---|
| `GET /api/selfhosted/nodes` | Registered nodes |
| `GET /api/selfhosted/status` | Server status |
| `GET /api/cloud/brain` | The activity stream |
| `GET /api/cloud/policies` | Policy state |
| `GET /api/cloud/cache/<key>` | A cached query result |
| `GET /api/export/events` | Bulk export |

Plus the approval relay:

| Endpoint | Purpose |
|---|---|
| `POST /api/approvals/request` | An agent asks |
| `GET /api/approvals/<id>` | Poll for a decision |
| `POST /api/selfhosted/approvals/<id>/decision` | A human answers |

## Configuration

| Variable | Effect |
|---|---|
| `CLAWMETRY_ENDPOINT` | Where nodes push |
| `CLAWMETRY_SELF_HOSTED` | Run in self-hosted mode |
| `CLAWMETRY_SELF_HOSTED_DB` | Database for the self-hosted server |
| `CLAWMETRY_SELF_HOSTED_E2E` | Whether content is end-to-end encrypted |
| `CLAWMETRY_CA_BUNDLE` | Custom CA bundle, for an internal certificate authority |

## Encryption on your own server

Keeping end-to-end encryption on means **even your own server cannot read
session content** — the browser decrypts it. That is the stronger position, and
it costs you server-side search over content.

Turning it off means your server holds readable transcripts, which is a coherent
choice if you already own that storage and want to query it. Decide deliberately;
the default is on.

## Air-gapped

Two extra pieces:

1. **A license that verifies offline.** Keys are verified cryptographically on
   the machine with no license-server call.
   → [license](/docs/cli/license/)
2. **No update checks.** `CLAWMETRY_AUTO_UPDATE=0` and `CLAWMETRY_OFFLINE=1`
   stop every outbound call.

```bash
export CLAWMETRY_OFFLINE=1
export CLAWMETRY_AUTO_UPDATE=0
clawmetry activate CLAW1.xxxxx
```

## Operating it

The same things you would run for any ingest service:

- **TLS**, with a certificate your nodes trust. Distribute an internal CA with
  `CLAWMETRY_CA_BUNDLE` if you use one.
- **Retention** on your side. Node-side retention bounds the local store; your
  server's is yours to set. → [Retention](/docs/data/retention/)
- **Backups** of whatever database you configured.
- **Access control** on the read surface. The ingest side authenticates nodes;
  who may *read* the dashboard is your policy.

## Tier

Self-hosted deployment is a licensed configuration.
`custom_data_residency` and `air_gapped_license` are Enterprise features.
→ [Plans and entitlements](/docs/ops/plans/)