Code Get started

Run a witness

Every witness makes the network harder to fool

Keepword counts networks, not machines. A witness in a new country, or at a provider nobody uses yet, makes every verdict harder to fake. Setting one up takes one command.

The network’s seed

seed1.keepword.net

New witnesses dial the seed to find the others. After that, every witness learns about every other one through gossip, and there is nothing special about the seed. It takes over from the first seed, w1.kxnode.net.

Before you start

What you need

A Linux server

1 vCPU, 1 GB of memory and 20 GB of disk are plenty to start. A small cloud server costs a few euros a month.

A domain name

An A record pointing at the server, and AAAA with IPv6. Pick a name you can keep: it’s how peers find the witness.

Ports 80 and 443

Open to everyone, so Caddy can get a certificate and peers can reach the API. Nothing else needs to be public.

An accurate clock

Time sync on. Messages more than five minutes off are rejected.

The server also needs to reach drand (api.drand.sh), the OpenTimestamps calendars and iptoasn.com over HTTPS.

Three steps

Join the network

The installer builds Keepword, runs it as a sandboxed service behind Caddy with automatic TLS, and dials the seed.

Back up /var/lib/keepword/witness.key. It is the witness’s identity. A lost key means a new witness, and the old log can never be extended.

  1. Install and point the witness at the seed

    Replace witness.example.org with the domain you pointed at the server.

    on your server 
    git clone https://git.keepword.net/keepword/keepword.git
cd keepword
sudo sh scripts/install.sh \
    --domain witness.example.org --caddy \
    --peer https://seed1.keepword.net

  2. Check that it joined

    After a few sync rounds, net peers lists the other witnesses with their networks, and net status shows the witness’s own location, corroborated by its peers, with no warnings at the end. 

    sudo keepword net peers
sudo keepword net status

  3. Keep it running

    Syncing, Bitcoin anchoring and the weekly ASN table refresh run by themselves. To upgrade, pull and re-run the installer with the same options. Keys and data are kept. 

    git pull
sudo sh scripts/install.sh \
    --domain witness.example.org --caddy \
    --peer https://seed1.keepword.net
# splits, silent edits and equivocations the witness has seen
sudo keepword alerts

What makes a network trustworthy

Independent, on purpose

A verdict says “witnesses in N independent networks saw this”. Keepword learns where a witness is from where its connections come from, never from what it says about itself.

Different providers usually mean different networks:

  • Hetzner AS24940
  • OVH AS16276
  • Scaleway AS12876
  • DigitalOcean AS14061
  • Vultr AS20473
  • Deutsche Telekom (home) AS3320

Three networks

“Agreed” needs witnesses in at least three autonomous systems. Two servers at the same provider are the same network, even in different data centers.

Two countries or more

Assignment takes at most two witnesses per country, so a request is seen from several places.

Different operators

The software can only check networks. Witnesses run by one person agree because one person runs them.

A public endpoint

Peers audit each witness’s log through its HTTPS endpoint. A witness without one is never assigned requests.

The network so far

Founding witnesses

The first independent witnesses, in the order they joined:

Witness Run by Country Network
seed1.keepword.net Keepword Germany Deutsche Telekom AS3320

Costs

What a witness uses

Each witness talks to a random sample of peers, so its costs barely depend on how big the network grows.

Network data roughly 25 to 50 GB a year, bounded by pruning
Own captures, normalized text only about 10 MB a day for 100 URLs checked hourly
Own captures, full pages 0.1 to 0.5 GB a day for the same, depending on the pages
Traffic a few hundred requests a minute

Operators decide what their witness keeps and shares. By default peers get hashes and signatures, never page content. Check your local law before running a public witness.