Quickstart
From nothing to a bot that answers in a group: set it up, register it with your account, add it to a group and run an example.
You need the VeilMesh app on your phone or computer, and a Linux machine with Docker where the bot runs (the image docker.io/veilmesh/bot, also ghcr.io/veilmesh/bot; x86-64 and ARM64). Replace https://your.relay with your relay's address as the app uses it (on the public relay, https://veilmesh.com).
1. Set up the bot
Work in a folder of its own. The image runs as an unprivileged user, so every command passes your own user id with --user; the bot's data stays in ./data, and its vault key in ./bot.key. A small shell function keeps the commands short:
mkdir veilmesh-bot && cd veilmesh-bot && mkdir data
umask 077
bot() {
docker run --rm --user "$(id -u):$(id -g)" \
-v "$PWD/data:/data" -v "$PWD/bot.key:/run/secrets/veilmesh_bot_vault_key:ro" \
-v "$PWD:/work" -w /work veilmesh/bot "$@"
}
docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/keys" \
-e VEILMESH_BOT_VAULT_KEY_FILE=/keys/bot.key veilmesh/bot keygen
bot init --relay https://your.relayinit prints the bot's Veil ID. Keep bot.key private: it unlocks the bot's keys.
On a private relay
On a private relay (your company's own), give the relay's join link instead of --relay. The bot checks that it reached that relay and remembers its key, the way the app does. The link's invite code is not used: the bot's account comes from its registration.
bot init --join-link 'https://veilmesh.com/join#…' Without a link, give --relay with the relay's fingerprint from its admin panel: --relay https://your.relay --relay-fp <fingerprint>. After init, register and run take the relay from the bot's vault, so --relay can be left out.
The relay's administrator decides whether bots are allowed there, and how many each member may have. While bots are off, the relay refuses to register the bot and the app offers no Suggest My Bot in that relay's groups. Turning them off later disconnects running bots; turning them on again lets them back in.
2. Register it with your account
On your primary device, open Profile → My Bots → Create Bot. A linked device cannot create or revoke bots: the certificate is signed with your account key, which only the primary holds. Paste the bot's Veil ID, give it a name, and say where it sends the messages it processes (nowhere, your own model, or named AI providers). The app shows the bot's certificate. Save it as bot.cert in the bot's folder and register:
bot register --relay https://your.relay --certificate bot.certThe registration is signed for that relay only: use the same address the app uses.
My Bots shows what your account's own relay knows. A bot registered only on a private relay that is not your account's own relay reads “not registered yet” there; in that relay's groups, Suggest My Bot asks the relay itself and offers the bot once it is registered there.
3. Run it
docker run -d --name veilmesh-bot --restart unless-stopped \
--user "$(id -u):$(id -g)" \
-v "$PWD/data:/data" -v "$PWD/bot.key:/run/secrets/veilmesh_bot_vault_key:ro" \
veilmesh/bot run --relay https://your.relay The bot's API listens on the container's loopback, never on a published port: put your own code in the same network namespace (--network container:veilmesh-bot). If you recreate the bot's container, restart your code's container too, so it joins the new one.
4. Add it to a group
If you created the group, open the group's settings, tap Add Bot and enter the bot's Veil ID. In a group someone else created, tap Suggest My Bot instead; the group's creator adds it with one tap.
5. Make it answer
Get the bot's token, then run the echo bot from the Python page next to it (save the example as echo_bot.py in the bot's folder):
bot token > token.json
docker run -d --name veilmesh-echo --network container:veilmesh-bot \
-v "$PWD:/work" -w /work python:3.12-slim \
sh -c "pip install -q veilmesh-bot && python3 -u echo_bot.py --token-file token.json" Write ping in the group: the bot answers pong. Type / and the app lists the bot's commands. The same example exists for JavaScript and Rust.
Revoking a bot
On your primary device, in My Bots, tap Revoke. Members' apps stop showing the bot's messages. The revocation goes to your account's relay and to the relay of every private relay group the bot is in; each of those relays switches the bot's account off, so it can no longer connect there, its webhook posts stop reaching the group, and your place for a bot is free again.
Alerts without code: a webhook
bot hook add --group <group id>
curl -d "Deploy finished" -H "X-VeilMesh-Hook-Secret: <secret>" \
http://127.0.0.1:8471/hooks/<group id>