> ## Documentation Index
> Fetch the complete documentation index at: https://snowseo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Self-hosting Beacon

> Beacon is MIT-licensed and its collector is open source. If you would rather not send crawler traffic to SnowSEO, run your own.

The client that installs on your site and the server that receives from it are both [open source, MIT-licensed](https://github.com/Snow-SEO/beacon). Nothing about beacon requires a SnowSEO account.

Point the `endpoint` at a server you control and the hits go there instead. Same client, same wire format, same classification.

***

## Why the split exists

Beacon is two halves, and it matters which half does what.

The **client** reports raw facts: the path, the `User-Agent` as received, the source address, whether Markdown was negotiated, any signature headers. It deliberately draws no conclusions.

The **server** decides what those facts mean: which crawler this is, and whether it is who it claims to be.

That split is not an implementation detail. A client that graded its own traffic would only be repeating what the crawler told it, and a crawler registry compiled into your site's dependencies goes stale the day after you install it.

<Note>
  This is why there is a server to self-host at all. If classification happened on your site, "self-hosting" would just mean not sending the data anywhere.
</Note>

***

## What you get, and what you do not

<CardGroup cols={2}>
  <Card title="You get" icon="check">
    Ingest, crawler classification, IP-range and reverse-DNS verification, Web Bot Auth signature checking, daily rollups, and storage in SQLite or Postgres.
  </Card>

  <Card title="You do not get" icon="xmark">
    A dashboard, a stats API, charts, alerting, crawl-to-referral attribution, or history beyond what your own database holds.
  </Card>
</CardGroup>

The reference server has exactly two routes: `POST /v3/beacon/hits` and `GET /health`. It records classified, verified hits into a database. What you do with them is yours.

If you want the dashboard, the maintained verified-crawler dataset and attribution, that is what hosted SnowSEO is. Both run the same `ingestBatch` function, so the open half cannot quietly drift from the hosted one.

***

## Three ways to do it

<Steps>
  <Step title="Run the reference server">
    One command, or a container. Storage in SQLite by default, Postgres if you want it. See [Running the server](/docs/beacon/self-hosting/reference-server).
  </Step>

  <Step title="Embed the pipeline in an app you already have">
    `@snowseo/beacon-server` exports `ingestBatch` on its own. Call it from your existing Fastify, Express or Hono app and persist however you like. Implement the `HitStore` interface for your own database.
  </Step>

  <Step title="Write your own collector">
    The [wire protocol](/docs/beacon/self-hosting/wire-protocol) is frozen and documented, so a collector in Go, Rust or Python is a supported path rather than a hack. You give up the classification engine, which is the hard part.
  </Step>
</Steps>

***

## Requirements

Node 24, or Node 22.5+ with `--experimental-sqlite`. The SQLite store uses Node's built-in driver, so there is no native module to compile and no dependency to install.

Postgres needs `pg`, declared as an optional peer dependency and imported only if you choose that store.

<Warning>
  The reference server has **no rate limiting and no TLS**. It is meant to sit behind a reverse proxy. Exposing it directly to the internet is not a configuration we support.
</Warning>