Answerbell docs
 v1.2.0
Live demo Get help
● Start · Production

Installation
your own server, with HTTPS.

Install Answerbell on a Linux server, compile it, put HTTPS in front of it, run it as a service and create the owner account.

LinuxCaddy or nginxsystemd

01Which computer runs the commands

The commands on this page run on the server (Ubuntu in the examples). You connect to it from your computer with ssh.

Windows

Use Windows Terminal / PowerShell only for ssh. To try Answerbell on your own PC, install WSL with Ubuntu and run the commands inside it, or use Git Bash. Production belongs on Linux. See Windows.

02Install

# Node.js 22, pnpm and build tools (Debian/Ubuntu)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs build-essential python3
sudo npm install -g pnpm
# the app
sudo mkdir -p /opt/answerbell && cd /opt/answerbell
# copy the contents of source/ from the package here, then:
pnpm install
cp .env.example .env
openssl rand -hex 32        # paste into .env as ADMIN_SECRET_KEY
pnpm test                   # offline test suite, no keys needed
pnpm build                  # compiles TypeScript to dist/ (run again after every update)
pnpm start                  # node dist/src/index.js

Production runs the compiled JavaScript in dist/. pnpm dev runs the sources and is for development only.

Not run on a fresh server while writing

The Node.js and pnpm lines are the standard NodeSource and npm procedure. The Answerbell commands (pnpm install, pnpm test, pnpm build, pnpm start) are the ones in README.md; the test suite, the build and the start of the compiled server were run on macOS while writing.

03About ADMIN_SECRET_KEY

In plain words: this one value locks everything sensitive. The keys you save in the console (ElevenLabs, Stripe, Resend, calendar apps) are encrypted with it, linked calendar tokens are sealed with it, and each client's tool secret is calculated from it.

  • Back it up next to your database backups. If you lose it, the saved keys cannot be read: you enter them again in the console and press Update agent on every client so the tools get their new secret.
  • Changing it is a rotation. Saved keys must be entered again and every client agent updated. Until a client's agent is updated its tool requests are refused (the agent apologises and takes no booking). Expect about one minute of interruption per client, so do it outside opening hours.
  • If .env has no key, one is generated into data/.admin-secret-key and the log says so. Move it into .env before going live.

04.env reference

Every variable is in .env.example. Most settings live in the console instead.

VariableDefaultWhat it does
ADMIN_SECRET_KEYgenerated64 hex characters (openssl rand -hex 32); encrypts saved keys, derives tool secrets
PORT / HOST8080 / 0.0.0.0Where the server listens. Behind a proxy use HOST=127.0.0.1
DATA_DIRdataWhere answerbell.sqlite and admin.sqlite live
PUBLIC_URLemptyThe https address ElevenLabs and Stripe call. Or set it in the console (Voice agent)
TRUST_PROXY / TRUST_PROXY_HOPS0 / 1Behind Caddy or nginx set 1; hops = proxies in front (Cloudflare + Caddy = 2)
ANSWERBELL_WORKERS10 stops the background call sync (for maintenance)
ELEVENLABS_API_KEY, STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, RESEND_API_KEYemptyOptional here; a value set here locks that console field
DEMO_MODE, ADMIN_DEMO_PASSWORD, ADMIN_DEMO_EMAIL, ADMIN_DEMO_NOTICEoffPublic read-only demo only. Leave empty on your server (Demo mode)
ELEVENLABS_AGENT_ID, ELEVENLABS_VOICE_ID, ELEVENLABS_API_BASE, ANSWERBELL_BUSINESS_NAME—Used only by the pnpm agent / pnpm latency commands, not by the server

05First start and the owner account

On the first start the log prints a one-time setup code. Open https://your-domain/admin, enter the code, your e-mail and a password of 12+ characters. That account is the owner. Then follow Deployment for HTTPS and the service, and Get started in the console.

06First steps in the console

  1. Get started walks through the required settings.
  2. Integrations: ElevenLabs API key, Resend API key (and Stripe keys to bill clients). Each has Test connection.
  3. Voice agent: the public URL; optionally model, voice and region.
  4. E-mail: the sender address on your Resend domain.
  5. Notifications: your own address for usage and payment notices.
  6. Clients → New client, then Create agent, then connect the number (Telnyx).
  7. Call the number.

07Backups

Everything is in DATA_DIR: answerbell.sqlite (clients, bookings, messages, calls, callers, invoices) and admin.sqlite (settings, encrypted keys, team, audit log). Copy both with the server stopped, or while it runs:

sqlite3 data/answerbell.sqlite ".backup backup-answerbell.sqlite"
sqlite3 data/admin.sqlite ".backup backup-admin.sqlite"

Keep ADMIN_SECRET_KEY with the backups. On Windows run these inside WSL.