Other guides

Self-hosting Keyoxide

Self-hosting is an important aspect to the Keyoxide project. Users need to trust the Keyoxide instance they're using to reliably verify identities. Making Keyoxide itself decentralized means no one needs to trust a central server, or the people that run it. If a friend or family member is hosting a Keyoxide instance, it becomes much easier to trust that instance!

Hosting only the Keyoxide web interface will result in some claim verifications failing as they cannot be performed in the browser, such as the DNS check. This is why you would perhaps want to host a so-called proxy instance as well. The instructions are below.

Using docker

Install docker and run:

docker run -d -p 3000:3000

To run the proxy, run:

docker run -d -p 3001:3000 -e ENABLE_MAIN_MODULE=false

Using docker-compose

    restart: always
        - 3000:3000
        - DOMAIN=localhost:3000
        - ENABLE_PROXY_MODULE=false
        - PROXY_HOSTNAME=localhost:3001
        - ONION_URL=

    restart: always
        - 3001:3000
        - DOMAIN=localhost:3001
        - ENABLE_MAIN_MODULE=false
        - IRC_NICK=
        - MATRIX_ROOM_ID=
        - XMPP_SERVICE=
        - XMPP_USERNAME=
        - XMPP_PASSWORD=

Using node

git clone
cd keyoxide-web
yarn # or npm install
yarn run start # or npm run start

Server configuration

You can configure keyoxide-web and keyoxide-proxy through the following environment variables.


Environment variableTypeRequiredDescription
DOMAINstringfalseThe domain on which the instance is hosted
ONION_URLstringfalseThe onion URL that points to the same instance
PORTintfalseThe port of the file server (default: 3000)
PROXY_HOSTNAMEstringfalseThe hostname of the keyoxide-proxy instance to use
ACTIVITYPUB_PUBLIC_KEYstringfalseThe public key used to simulate an ActivityPub account and sign HTTP requests


Environment variableTypeRequiredDescription
DOMAINstringfalseThe domain on which the instance is hosted
ACTIVITYPUB_URLstringfalseThe URL of the simulated ActivityPub account (https://KEYOXIDE_WEB_DOMAIN/user/keyoxide)
ACTIVITYPUB_PRIVATE_KEYstringfalseThe private key used to simulate an ActivityPub account and sign HTTP requests
IRC_NICKstringfalseThe nick of your IRC verifier account
MATRIX_ACCESS_TOKENstringfalseThe access token of your Matrix verifier account
MATRIX_INSTANCEstringfalseThe instance of your Matrix verifier account
MATRIX_ROOM_IDstringfalseMust be !
TELEGRAM_TOKENstringfalseThe token for the Telegram Bot API
XMPP_SERVICEstringfalseThe hostname of your XMPP verifier account
XMPP_USERNAMEstringfalseThe username of your XMPP verifier account
XMPP_PASSWORDstringfalseThe password of your XMPP verifier account

All of these settings are optional but you will need to provide all the settings for each service (matrix, twitter, etc) for that verification to work.

Claim verification configuration

Some service providers require additional steps and server configuration to get identity verification working on their platforms.

If a service provider is not listed below, no further steps are required and identity verification is working right away.

For ActivityPub claim verification

Some ActivityPub-compatible instances require their API calls to be signed. To accomplish this, the Keyoxide instance can simulate an ActivityPub account. The following commands generate the public and private keys needed for the server configuration:

openssl genrsa -out private.pem 2048
openssl rsa -in private.pem -outform PEM -pubout -out public.pem
while read -r line; do echo -nE "$line\n" ; done < public.pem > public-oneline.pem

For IRC claim verification

Simply decide on a unique nickname that should always be available when a claim needs to be verified. There is no need to register the nickname beforehand on any IRC server.

For Matrix claim verification

For Matrix verification to work, create a dedicated Matrix account and make it a member of the room. Provide the login details to the keyoxide-proxy instance.

For Telegram claim verification

Follow the standard Telegram instructions to obtain an API token. In short, start a conversation with the @BotFather, issue the /newbot command and follow the steps until you are given the API token.

For XMPP claim verification

Create a dedicated XMPP account and provide the login details to the keyoxide-proxy instance.