Aequitas Bio Verifier Guide v2.0 · August 2026
Step by step · No cryptography knowledge required · About 45 minutes, most of it waiting
The steps below are in English. The sections above — what this is, what it protects, and what you take on — are in your language.
What is a bio verifier? When somebody registers as a human, their face has to be checked against everyone already registered — otherwise one person could register twice and draw two incomes. A bio verifier is a machine that performs that check. It never sees the picture: the image is discarded after checking, and what the service keeps is an encrypted template. A split-share mode exists in which no single service holds a whole one and the comparison happens jointly — it is built and tested but not active yet, because its threshold has never been calibrated. Until it is, each service holds a whole encrypted template.
What is a coordinator? The verifier answers questions; the coordinator asks them. It is the door a person arrives at: it hands out the challenge, passes the capture to the verifiers, counts their answers, and issues the certificate the chain pays out on. You will run both on one server — two programs, not two machines.
What is a committee? The group of verifiers asked about one registration. It only counts once several of them agree. That is the entire point: one broken or dishonest machine cannot wave anybody through.
Before You Start — What You Need
1. A registered Aequitas human account. Same rule as for block production, and for the same reason: one human, one key. Without it, one person could quietly become a whole committee.
2. A small Linux server. 2 GB of RAM is enough. Any provider works — Contabo, Hetzner, DigitalOcean — for roughly 5–10 € a month. A machine at home is a poor choice: it has to stay reachable.
3. A domain name you control. Something like verifier.example.org. A subdomain of one you already own is fine. Browsers hand out no camera to a page without HTTPS, and HTTPS needs a name.
4. About 45 minutes. Most of it waiting for downloads. Nothing here needs any knowledge of cryptography — every command is given in full.
5. The intention to stay online. Every member of a committee must answer for a registration to finish. A verifier that is often away slows people down instead of protecting them.
Step 1 — Rent a Server
What is a VPS? A computer in a data centre that you rent and control remotely, as if it stood under your desk. It stays on when your laptop does not.
a) Open any provider — contabo.com, hetzner.com and digitalocean.com all work
b) Choose the smallest plan with at least 2 GB RAM
c) Choose Ubuntu 24.04 (or 22.04) as the operating system
d) Note the IP address and root password they send you
Step 2 — Log In and Install Docker
What is Docker? A way to run a program together with everything it needs, in one sealed package. You never install databases or libraries by hand, and what runs on your machine is exactly what runs on everyone else’s.
On Windows open PowerShell; on macOS or Linux open Terminal. Then:
# Use the IP address from Step 1
ssh root@YOUR-SERVER-IP
# Installs Docker. Takes a couple of minutes.
curl -fsSL https://get.docker.com | sh
# Should print a version number
docker --version
Step 3 — Point Your Domain at the Server
What is an A record? The entry in your domain’s settings that says which IP address a name points to. Without it nobody can reach your server by name, however well it is running.
a) Open the DNS settings wherever your domain is managed
b) Add an A record: name verifier, value = your server’s IP address
c) Save, wait a few minutes, then check with ping verifier.example.org
Step 4 — Generate Your Own Keys
What is a key pair? Two matching halves. The private half signs; the public half lets anyone check a signature without being able to forge one. You publish the public half and show the private one to nobody.
Generate them yourself. Never accept keys from anybody, including us. Two verifiers holding the same secret count as one, and the quorum that is meant to protect people would look satisfied without being so.
# 1 — encrypts what little is stored on disk
openssl rand -base64 32
# 2 — defines your own projection, see the note below
openssl rand -hex 32
# 3 — your Ed25519 attestation key pair
docker run --rm python:3.12-slim sh -c "pip -q install cryptography && python -c '
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
from cryptography.hazmat.primitives import serialization as s
k = Ed25519PrivateKey.generate()
print(\"PRIVATE\", k.private_bytes(s.Encoding.Raw, s.PrivateFormat.Raw, s.NoEncryption()).hex())
print(\"PUBLIC \", k.public_key().public_bytes(s.Encoding.Raw, s.PublicFormat.Raw).hex())'"
Copy all four values into a text file for the next step, and keep the private half on your server and nowhere else. Your own projection seed matters: every verifier must project faces the same way to compare them, but a public projection would let a stolen fragment be reversed. Yours being yours is what prevents that.
Step 5 — Write the Configuration File
Put the values from Step 4 into a file only you can read.
nano /root/.aequitas-verifier.env
# --- paste, with your own values ---
TEMPLATE_ENCRYPTION_KEY=<the base64 value>
FACE_SKETCH_SEED=<the hex value>
VALIDATOR_SIGNING_KEY=<the PRIVATE hex from Step 4>
ALLOW_REAL_BIOMETRIC_DATA=false
POH_DB_PATH=/data/poh.db
PORT=8098
# Ctrl+O, Enter, Ctrl+X leaves nano
chmod 600 /root/.aequitas-verifier.env
Leave ALLOW_REAL_BIOMETRIC_DATA on false until you have read the data-protection sections above and know what you are taking on. With it false your verifier works fully — on test data.
This is where the guide stops today. The image below is real and its name is final, but the package is still private — the pull will be refused with denied unless you were given access. Everything before this step works right now, and everything after it will work the day the package is opened, with no change to these instructions. We would rather show you the wall than hide it.
Step 6 — Start the Verifier
docker network create aequitas-net 2>/dev/null || true
mkdir -p /root/aequitas-verifier-data
docker run -d --name aequitas-verifier
--network aequitas-net --restart unless-stopped
--env-file /root/.aequitas-verifier.env
-v /root/aequitas-verifier-data:/data
--log-opt max-size=20m --log-opt max-file=3
ghcr.io/hanoi96international-gif/aequitas-biometric-beta/matching:latest
# If this says "denied" or "unauthorized", the image
# is not published publicly yet. That is on us, not on you —
# tell us and it gets released.
# Did it come up?
curl -s localhost:8098/health
A healthy answer reports plaintext_templates: 0 and sketch_seed_configured: true. The first is the plaintext-template counter and must stay at zero; the second confirms your own projection from Step 4 is in use rather than the built-in default.
Step 7 — Put HTTPS in Front
What is a reverse proxy? A small program that receives requests from the internet and passes them to your verifier, handling the encryption certificate for you. Caddy obtains and renews that certificate automatically and free of charge.
# nano /root/Caddyfile — use your own domain
verifier.example.org {
reverse_proxy aequitas-verifier:8098
}
docker run -d --name caddy --network aequitas-net --restart unless-stopped
-p 80:80 -p 443:443
-v /root/Caddyfile:/etc/caddy/Caddyfile
-v /root/caddy-data:/data
caddy:latest
# From your own computer, not the server:
curl -s https://verifier.example.org/health
Step 8 — Bind Your Verifier Key to Your Wallet
Why does this exist? This is what makes one human one verifier. Your wallet signs a sentence naming your key. Without it, anybody could enter a key that is not theirs, or one person could quietly be several verifiers — and a committee of one person pretending to be five protects nobody.
Signing costs nothing and moves nothing: it signs a sentence, not a transaction. Open the button below, paste the PUBLIC half from Step 4, and sign with the wallet of your registered account.
Step 9 — Register It on the Chain
Your public key and your HTTPS address go into the validator registry on the chain, together with the signature from Step 8. From then on your attestations count toward the quorum.
# On your server. Every value here is public.
curl -s -X POST https://aequitas.digital/api/register-validator-key
-H "Content-Type: application/json"
-d '{"signing_address":"0xYOUR-WALLET",
"human_wallet":"0xYOUR-WALLET",
"signature":"0xSIGNATURE-FROM-STEP-8",
"personhood_key":"YOUR-PUBLIC-HEX",
"matching_url":"https://verifier.example.org"}'
Nobody approves this. Until August 2026 you had to send your key to us and wait for somebody to add it to a file on every machine — which made that person a gatekeeper. Nothing secret leaves your server here: the private half stays where it was made.
Step 10 — Start Your Coordinator
The second program, on the same server. It generates its own two keys with permissions only root can read, starts the container, and prints its public key. Nothing to copy in beforehand, nothing to send anywhere.
./eigenen-coordinator-starten.sh verifier.example.org
# It ends by printing your coordinator public key.
# Write it down — Step 11 needs it.
That key is not in your wallet. MetaMask only ever shows addresses; this one belongs to the coordinator, not to you. Never paste its private half into any page, including ours.
Step 11 — Authorize It, and You Are Done
What happens here? The page asks your coordinator for its own key, your wallet signs one sentence naming it, and the page registers that on every node. Three parties, one click, no terminal.
Open the button below and enter your coordinator’s address — the same https:// address from Step 7. There is no key to look up and nothing to copy back: your coordinator proves possession of its key where that key lies, and it never leaves that machine.
Until August 2026 this step printed a command for you to run over SSH — and it was missed three times in a row, silently: signed but never registered, with nothing on screen saying so. A step that needs a terminal is, for most people, not a step at all.
Checking That It Works
# Reachable from outside, with a valid certificate?
curl -s https://verifier.example.org/health
# Does the network see you and agree with the others?
curl -s https://aequitas.digital/inventory
The second call lists every verifier and compares them: whether all hold the same number of enrollments, whether anyone is missing a seed, and whether the keys agree. If your entry shows a divergence, it is better to find out here than during someone’s registration.
If Something Goes Wrong
a) connection refused — the container is not running. docker logs aequitas-verifier says why; a missing value in the env file is the usual cause.
b) No certificate appears — your A record from Step 3 has not propagated yet, or port 80 is blocked. Caddy needs port 80 reachable to obtain one.
c) sketch_seed_configured: false — FACE_SKETCH_SEED did not reach the container. Check the env file for stray quotes, then docker restart aequitas-verifier.
d) Your coordinator is reported as an unknown key — Step 11 did not finish. Open it again: the page lists each node it reached, and a node that was unreachable at the time is named there rather than passed over in silence.
e) Still stuck — ask in the Telegram group linked on the front page. Include the output of the two checks above, and never paste any private key.
Where this stands today — plainly
This part is in beta and the limits are real. The joint comparison consumes one-time cryptographic material, and one delivery currently covers a few dozen registrations before more is needed — so the confidential path proves itself at small scale first, not at millions. The work also grows with the number of people enrolled. We publish these numbers rather than round them off: a system that asks for your face has no business being vague about what it can and cannot do yet.
Erasure by wallet address only works at the coordinator where the enrolment was made: your marker hangs on your key, and another coordinator derives a different one for the same address. A "not found" from elsewhere therefore means "not registered here", not "not registered" — and the answer says so. The route through a person's own bio_hash, the one that belongs to them and needs no operator at all, works at every coordinator, because that identifier stays the same.