Quick start

This gets Reception AI running on your laptop. You need Node.js 22 and npm; nothing else is required for a first look.

1. Install and start#

From the folder you unzipped:

npm install
cp .env.example .env
npm run dev

Open http://localhost:8080. Create an account at /login, then open /app to reach your workspace.

2. Turn on the AI#

Open .env and add your keys, then restart npm run dev:

# Chat, the website widget, voice previews and rehearsals
XAI_API_KEY=xai-...

# Live voice: the homepage "Start talking" demo and live phone calls
OPENAI_API_KEY=sk-...

Without XAI_API_KEY, chat answers "AI is not available in this environment". Without OPENAI_API_KEY, the homepage voice demo falls back to typed chat.

3. Create a receptionist#

In the workspace, choose Pick a starting point and select a template close to your business (Salon & spa, Dental practice, Home services and so on), or Tell us about you to have the AI builder draft one. Then:

1. Open Hours and save your opening hours and timezone. No booking slots exist until you do.
2. Open Knowledge and add a note or upload a document about your services.
3. Use the Talk panel on the right to chat with it, or Practice to run a scripted rehearsal.

Building a receptionist covers every tab.

4. Make yourself an admin (optional)#

The admin panel at /admin is where plans, configuration and service health live. Locally:

1. Add your address to .env and restart:

   .envCopy

   ADMIN_EMAILS=you@example.com

2. Sign up with that address (if you already have an account with it, sign in), then visit /admin.

3. Without SMTP configured, the confirmation link is printed in the terminal running npm run dev. Look for lines starting with [admin] and open the link in the same browser.

First admin and the admin panel explains why the extra confirmation step exists.

5. Keep your data (optional)#

Point the app at a real Postgres so data survives restarts. A local Docker container is enough:

docker run -d --name reception-ai-db -p 5432:5432 \
  -e POSTGRES_PASSWORD=postgres postgres:16

DATABASE_URL=postgres://postgres:postgres@localhost:5432/postgres
CREDENTIAL_ENCRYPTION_KEY=   # generate with: openssl rand -base64 32
BETTER_AUTH_SECRET=          # generate with: openssl rand -base64 32

Then apply the schema and restart:

npm run db:migrate
npm run dev

6. Receive real calls on your laptop (optional)#

Carriers need a public HTTPS address to reach you. The bundled tunnel script uses Cloudflare's free quick tunnels:

# needs cloudflared installed, e.g. brew install cloudflared
npm run tunnel

It prints an APP_URL=https://….trycloudflare.com line along with the exact webhook URLs to paste into Twilio or Plivo. The script does not edit any files:

1. Copy the APP_URL= line into .env. Put it in .env rather than only in the admin panel: the development server's host check reads the environment.
2. Restart npm run dev.
3. Import your number under Phone numbers and follow Phone numbers and carriers.

The tunnel hostname changes every time you run it, so repeat these steps after each restart.

Good to know in development#

• Background jobs do not run on their own under npm run dev. The every-minute drain only runs in a built server. To process queued work locally (campaigns, call reconciliation), call the drain from the same machine:

  TerminalCopy

  curl http://localhost:8080/api/jobs/run

• Trying a production build locally. npm start does not read .env. Pass it explicitly:

  TerminalCopy

  npm run build:app
  PORT=8080 node --env-file=.env .output/server/index.mjs

Next steps#

• Installation and deployment for a real server.
• Configuration for every variable and admin setting.