OpenNoddDocs
On this pageTelegram bot

Self-hosting

Telegram, GitHub and voice

Set up the optional extras on your own server - the Telegram bot, the GitHub App and the ElevenLabs voice key.

All three are optional and off until you set their variables in .env. After changing .env, run docker compose up -d so the gateway restarts with the new values.

#Telegram bot

Telegram lets owners approve requests and reply from their phones. It uses one bot for your whole server.

  1. In Telegram, open a chat with @BotFather and send /newbot. Follow the questions. BotFather gives you a token and you choose the bot's username.

  2. Add them to .env:

    sh
    NODD_TELEGRAM_BOT_TOKEN=<token from BotFather>
NODD_TELEGRAM_BOT_USERNAME=<username without the @>

  3. Restart the gateway: docker compose up -d.

  4. Check the log for the line Telegram bridge running as @yourbot:

    sh
    docker compose logs gateway | grep -i telegram

The bridge asks Telegram for updates (long polling), so your server does not need a public address for it.

If the token is wrong, the server stops at start-up with a Telegram error. Fix the token and start again.

Each person then links their own account: settings, Link Telegram. See Telegram.

#GitHub App

"Connect GitHub" lets people link a repo to a chat so agents can push branches and open pull requests. It works through a GitHub App that you create once for your server. Agents get a key for one repo that expires within the hour. Nobody shares a lasting token.

#1. Create the app (about 5 minutes, on github.com)

Open https://github.com/settings/apps/new and fill in:

Field Value
GitHub App name OpenNodd (or OpenNodd <yourname> if taken)
Homepage URL https://nodd.example.com
Callback URL https://nodd.example.com/v1/github/callback
Request user authorization (OAuth) during installation ticked
Webhook, Active unticked
Repository permissions, Contents Read and write
Repository permissions, Pull requests Read and write
Where can this GitHub App be installed? Any account, so the people you work with can use it

Click Create GitHub App. On the page that opens:

  1. Note the App ID and the Client ID.
  2. Note the app's URL name (the slug): the end of its public page, github.com/apps/<slug>.
  3. Click Generate a new client secret and copy it.
  4. Click Generate a private key. A .pem file downloads.

#2. Give the details to the server

Turn the key into one line, then add everything to .env:

sh
base64 -w0 your-app.private-key.pem
sh
NODD_GITHUB_APP_ID=123456
NODD_GITHUB_APP_SLUG=opennodd
NODD_GITHUB_CLIENT_ID=<client ID>
NODD_GITHUB_CLIENT_SECRET=<client secret>
NODD_GITHUB_APP_KEY=<the base64 line>

Restart the gateway. GitHub is on when the App ID and the key are both set. People then see the ⎇ button in chats that have an agent. See Connect GitHub.

Note

Make sure NODD_PUBLIC_URL matches the callback address you gave GitHub. Keep the .pem file and the client secret private.

#Stop it

People can unlink a repo in the chat. You can remove repos, or the whole app, on GitHub under Settings, then Applications.

#Voice

Voice uses ElevenLabs for speech-to-text, text-to-speech and the list of voices.

  1. Create an ElevenLabs account and an API key (it starts with sk_).

  2. Add it to .env:

    sh
    NODD_ELEVENLABS_API_KEY=sk_...

  3. Restart the gateway.

The voice button now appears in the web app. If it does not, or an error says "The ElevenLabs key was refused", check the key.

  • Voice needs the microphone, which browsers only allow on https:// pages (and on localhost). Set up HTTPS first.
  • Your server's ElevenLabs account is used for everyone, so their usage counts on that account.
  • Speech recognition is set to English.

See Voice for how people use it.