Quickstart: Binary

This chapter takes you from a LiteBot bundle to a binary running under pm2, with a first admin login and a test chat. It assumes a Linux server that you manage.

Before you start

You need:

• A Linux x86-64 server. The binary targets node18-linux-x64 and does not need Node.js itself; pm2 does.
• The LiteBot bundle: the litebot binary and the public/ dashboard folder (see Build if you produce the bundle yourself).
• A MongoDB connection string and database name.
• An API key for at least one language model provider.

LiteBot listens on one port for HTTP and both WebSockets. The shipped .env.example sets PORT=3345, and this manual uses 3345 everywhere. With PORT unset, the code falls back to 3000.

Build

Skip this section if you received a ready bundle. Whoever produces the bundle runs, in the repository (with dependencies installed in the root and in frontend/):

npm run build:full
md5sum dist/litebot

This builds the dashboard into public/ and then packs the server into dist/litebot with pkg. Dashboard feature flags are fixed at this point: to show the auto-dialer or the visual flow editor, build with VITE_ENABLE_AUTO_DIALER=true or VITE_ENABLE_VISUAL_EDITOR=true in the environment. The server needs its own flag as well (ENABLE_AUTO_DIALER, ENABLE_VISUAL_EDITOR); see Auto-dialer and Visual flows. Ship dist/litebot and public/ together, with the checksum.

What the binary contains

The binary bundles the server code (src/) and its npm libraries. These items are read from disk at run time, relative to the working directory or to the binary's own directory, so they must sit beside it:

Tools on disk cannot require() npm packages, because the binary cannot resolve node_modules for files outside itself. See Tools.

Install

Copy the binary, the dashboard and your configuration into one directory on the server:

sudo mkdir -p /opt/litebot/config/bots /opt/litebot/config/prompts /opt/litebot/config/tools
cd /opt/litebot
# copy litebot and public/ from the bundle into this directory
sudo chmod 755 litebot
sudo touch .env
sudo chmod 600 .env

The layout should now look like this:

/opt/litebot/
  litebot          binary
  public/          dashboard
  config/bots/  config/prompts/  config/tools/
  .env             you fill this in below

Run the binary with /opt/litebot as its working directory. It reads .env, public/, data/ and logs/ relative to the working directory, and config/ relative to the binary.

Minimal .env

PORT=3345
NODE_ENV=development
MONGODB_URI=mongodb://127.0.0.1:27017
MONGODB_DB_NAME=litebot
JWT_SECRET=<random string of at least 32 characters>
GEMINI_API_KEY=<your key>
GEMINI_MODEL=models/gemini-2.5-flash
DEFAULT_LLM_PROVIDER=gemini
ADMIN_USERNAME=admin
ADMIN_PASSWORD_HASH=<salt:hash, see below>

Generate the secret with openssl rand -hex 32. Never change JWT_SECRET on a running installation: existing logins become invalid and per-tenant provider keys stored in MongoDB can no longer be decrypted.

Any one provider key is enough to start: GROQ_API_KEY, OPENROUTER_API_KEY, GEMINI_API_KEY, OPENAI_API_KEY, SARVAM_API_KEY, or OLLAMA_ENABLED=true. A provider registers whenever its key variable is non-empty, so do not copy placeholder values such as your_groq_api_key_here from .env.example: they register a provider that fails on every request. See LLM providers.

NODE_ENV=production changes several behaviours, including a much lower request rate limit and no reload endpoints. Read What NODE_ENV changes before you set it.

First admin login

On a new database there are no dashboard users. LiteBot then accepts one login from .env: ADMIN_USERNAME (default admin) with the password whose scrypt hash is in ADMIN_PASSWORD_HASH. The hash format is salt:hash in hex. This command produces it with plain Node.js:

node -e "const c=require('crypto');const s=c.randomBytes(32);console.log(s.toString('hex')+':'+c.scryptSync(process.argv[1],s,64,{N:16384,r:8,p:1}).toString('hex'))" 'your-password'

Put the output in ADMIN_PASSWORD_HASH. The password must be at least 6 characters. The .env login is used only while no user with that username exists in the users collection. Once you create a real admin user in the dashboard, that user takes over. See Users, roles and tenants.

Run under pm2

cd /opt/litebot
sudo pm2 start ./litebot --name litebot --cwd /opt/litebot --kill-timeout 10000
sudo pm2 save
sudo pm2 startup

pm2 startup prints one command. Run it so pm2 and LiteBot start at boot. If pm2 tries to run the binary through Node.js, start it again with --interpreter none.

At start, LiteBot connects to MongoDB, creates its indexes, seeds the default roles and the default tenant, loads bots and tools, and then listens. A healthy start logs lines like these:

Connected to MongoDB successfully
Loaded 1 bots and 12 tools
Server is running on port 3345 in development mode

Check it is up

curl -s http://127.0.0.1:3345/health

{ "status": "healthy" }

/health pings MongoDB. It returns 503 with "status": "unhealthy" when the database is unreachable. For the other probes see Health probes.

Log in to get a token:

curl -s -X POST http://127.0.0.1:3345/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"your-password"}'

The reply carries data.token, valid for JWT_EXPIRES_IN (default 24h). Open http://<server>:3345/ in a browser to use the dashboard with the same credentials.

First chat

Create a minimal bot file at config/bots/clinic-reception.json:

{
  "id": "clinic-reception",
  "name": "Clinic Reception",
  "systemPrompt": "You are the reception assistant of a small clinic. Answer briefly.",
  "provider": "gemini"
}

Restart LiteBot (sudo pm2 restart litebot), or let hot reload pick the file up when it is on (see Hot reload). Then send a message. POST /api/chat needs no login:

curl -s -X POST http://127.0.0.1:3345/api/chat \
  -H 'Content-Type: application/json' \
  -d '{"botId":"clinic-reception","message":"What are your opening hours?"}'

{
  "success": true,
  "data": {
    "response": "We are open Monday to Saturday ...",
    "sessionId": "sess_mf3k2x9a7q1b2c3d",
    "botId": "clinic-reception",
    "usage": { "...": "..." }
  }
}

Send the returned sessionId with the next message to continue the same conversation. The full request and response are in Chat API.

Upgrading

1. Copy the new bundle to the server: the binary as litebot.new, and the new public/ as an archive.

2. Compare checksums:

   cd /opt/litebot
   md5sum litebot.new litebot

3. Wait for a quiet moment. A restart cuts live voice sessions and in-flight chat turns.

4. Back up the current binary, dashboard and .env, then swap and restart:

   TS=$(date +%Y%m%d%H%M)
   cp -p litebot litebot.bak.$TS && cp -a public public.prev.$TS && cp -p .env .env.bak.$TS
   mv litebot.new litebot && chmod 755 litebot
   # replace public/ with the new dashboard build
   sudo pm2 restart litebot --update-env

5. Check /health again and send one test chat.

Some releases ship database migration scripts. Run them as their release notes say before or after the swap.

To roll back, restore the backups and restart:

cp -p litebot.bak.<ts> litebot
rm -rf public && cp -a public.prev.<ts> public
sudo pm2 restart litebot --update-env

Where to go next

• Learn the dashboard: Dashboard
• Build a real bot: Bots
• Run it day to day: Operations
• Lock it down: Security