AgentLabs Setup Guide

Install Node.js 20 and System Tools

# Update system packages
sudo apt-get update && sudo apt-get upgrade -y

# Install Node.js 20.x LTS
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify versions
node --version   # Should show v20.x.x
npm --version

# Install PM2 process manager globally
sudo npm install -g pm2Copy

Install and Configure PostgreSQL

# Install PostgreSQL
sudo apt-get install -y postgresql postgresql-contrib

# Start and enable PostgreSQL
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Create database and user
sudo -u postgres psql <<EOF
CREATE DATABASE agentlabs;
CREATE USER agentlabs_user WITH ENCRYPTED PASSWORD 'your_secure_password_here';
GRANT ALL PRIVILEGES ON DATABASE agentlabs TO agentlabs_user;
\q
EOFCopy

Download and Extract AgentLabs

# Create application directory
sudo mkdir -p /root/agentlabs
cd /root/agentlabs

# Upload your AgentLabs zip file and extract
unzip AgentLabs-v5.3.7.zip -d .

# Ensure plugins directory exists (for add-ons)
mkdir -p plugins
touch plugins/.gitkeepCopy

Create the Environment File

Create a .env file in the application root with the following required variables:

# ─── Core ───────────────────────────────────
NODE_ENV=production
PORT=5000
APP_URL=https://yourdomain.com
BASE_URL=https://yourdomain.com

# ─── Database ────────────────────────────────
DATABASE_URL=postgresql://agentlabs_user:your_secure_password_here@localhost:5432/agentlabs

# ─── Security (generate with the command below) ──
SESSION_SECRET=<64-char-random-string>
JWT_SECRET=<64-char-random-string>

# Generate secure secrets:
# node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"Copy

Install Dependencies and Build

# Install all npm packages
npm install

# Build the frontend (Vite) and backend (esbuild)
npm run buildCopy

Initialize the Database Schema

# Push the Drizzle schema to the database
# This creates all tables, indexes, and default data
npm run db:pushCopy

Install Plugins (Optional)

If you have purchased add-on plugins, install them now before starting the application:

# Extract plugin zips into the plugins/ directory
unzip AgentLabs-SIPEngine-Plugin-v2.0.0.zip -d plugins/
unzip AgentLabs-TeamManagement-Plugin-v2.0.0.zip -d plugins/
unzip AgentLabs-RESTAPI-Plugin-v1.0.0.zip -d plugins/Copy

Start with PM2

# Start the application
pm2 start npm --name "agentlabs" -- start

# Or using the ecosystem config (if included)
pm2 start ecosystem.config.cjs

# Save PM2 config to survive server reboots
pm2 save
pm2 startupCopy

Configure Nginx Reverse Proxy and SSL

See the Nginx & SSL section for the complete Nginx configuration and SSL certificate setup with Let's Encrypt.

Back Up Your Database

# Create a database backup
pg_dump -U agentlabs_user -d agentlabs -f ~/backup_$(date +%Y%m%d).sql

# Verify the backup was created
ls -lh ~/backup_*.sqlCopy

Download and Prepare the New Version

# Upload the new zip to your server, then:
cd /tmp
unzip AgentLabs-v5.3.7.zip -d agentlabs-newCopy

Preserve Critical Files Before Overwriting

# Copy your .env to a safe location
cp /root/agentlabs/.env ~/agentlabs.env.backup

# Backup your plugins directory
cp -r /root/agentlabs/plugins ~/agentlabs-plugins-backupCopy

Apply the Update

# Copy new files over the existing installation
# (rsync is preferred — excludes .env and plugins/)
rsync -av --exclude='.env' --exclude='plugins/' \
  /tmp/agentlabs-new/ /root/agentlabs/

# Restore .env if it was overwritten
cp ~/agentlabs.env.backup /root/agentlabs/.env

# Restore plugins
cp -r ~/agentlabs-plugins-backup/* /root/agentlabs/plugins/Copy

Install New Dependencies

# Install any newly added npm packages
cd /root/agentlabs
npm installCopy

Run Database Migrations

# Apply schema changes from the new version
# Use db:migrate (safe, non-destructive) — NOT db:push in production
npm run db:migrate

# If no migration script is provided, use db:push
# npm run db:pushCopy

Rebuild and Restart

# Build the frontend with new changes
npm run build

# Restart the application
pm2 restart agentlabs

# Watch logs to verify healthy startup
pm2 logs agentlabs --lines 50Copy

Verify the Upgrade

Check startup logs for the health check confirmation:

[Startup] Health check PASSED
   Database: OK - All tables present
   Environment: All required variables present
   ✓ Server fully initialized on port 5000Copy

Also visit Admin → System → Version to confirm the version number updated.

Run the Installation Wizard

Visit https://yourdomain.com. You'll be redirected to /install automatically.

• Enter your name and email for the super admin account
• Set a strong password (at least 8 characters, mix of letters and numbers)
• Set your platform name (shown in emails and the UI)

Configure Essential Settings in Admin Panel

After logging in, navigate to Admin → Settings and configure:

• Telephony: Add Twilio or Plivo credentials
• AI Providers: Add at least one ElevenLabs API key
• Email: Configure SMTP so users receive notifications
• Payments: Enable at least one payment gateway
• Branding: Upload your logo and set colors

Create Your First Agent

Navigate to My Agents → Create Agent. Give it a name, select an ElevenLabs voice, write a system prompt, and assign a phone number (purchased from Twilio through the platform).

Test With a Call

Use the Test Call button on the agent to verify everything is working end-to-end before launching campaigns.

Choose an Email Provider

Use any SMTP-compatible service. Recommended providers for transactional email:

• SendGrid — Reliable, good deliverability, generous free tier
• Mailgun — Developer-friendly, good EU region support
• Amazon SES — Very cost-effective at scale
• Postmark — Best-in-class deliverability
• Gmail SMTP — Only for low-volume development/testing

Configure SMTP Settings

Go to Admin → Settings → Email:

Test the Email Configuration

Click the Send Test Email button. You should receive a test message within 30 seconds. If not, check your spam folder and SMTP credentials.

Upload Documents

Navigate to Knowledge Base in your user dashboard. Click Upload Document or enter a URL to scrape.

Automatic Processing Pipeline

• Chunking: Documents are split into smaller segments (~500 tokens each)
• Embedding: Each chunk is converted to a 1536-dimensional vector via OpenAI
• Indexing: Vectors are stored in the database for fast retrieval

Assign Documents to Agents

When creating or editing an agent, select which knowledge base documents it should use. An agent can have multiple documents assigned.

Runtime Context Injection

During a call, when a question is detected, the system performs a vector similarity search against the assigned documents and injects the most relevant chunks into the ElevenLabs conversation context.

Configure Appointment Settings

Ensure your working hours and buffer settings are configured in the Appointments Settings tab before enabling booking on agents.

Enable on Your Agent

When creating or editing an agent, find the Appointment Booking toggle in the agent settings. Enable it and configure the default service name and appointment duration.

Automatic Tool Registration

AgentLabs automatically creates a book_appointment tool in your ElevenLabs agent configuration. The tool includes the current date context and your webhook URL — no manual ElevenLabs configuration needed.

Test a Booking

Make a test call to your agent. When prompted, say something like "I'd like to schedule an appointment for tomorrow at 2pm." The agent should confirm and the appointment should appear in your dashboard within seconds.

Create a Google Cloud Project

Go to console.cloud.google.com. Click Select a project → New Project. Give it a name (e.g., "AgentLabs Integration") and click Create.

Enable the Google Sheets API

1. In your project, go to APIs & Services → Library
2. Search for "Google Sheets API"
3. Click on it and click Enable
4. Wait about 30 seconds for the API to activate

Configure the OAuth Consent Screen

1. Go to APIs & Services → OAuth consent screen
2. Choose External (unless you have a Google Workspace account)
3. Fill in App name, user support email, and developer contact email
4. Under Scopes, add: https://www.googleapis.com/auth/spreadsheets
5. Under Test users, add your Google account email
6. Click Save and Continue through all steps

Create OAuth 2.0 Credentials

1. Go to APIs & Services → Credentials
2. Click Create Credentials → OAuth client ID
3. Application type: Web application
4. Name: e.g., "AgentLabs OAuth Client"
5. Under Authorized redirect URIs, click Add URI and enter:

{APP_URL}/auth/google/callbackCopy

Replace {APP_URL} with your actual domain. Click Create. A dialog shows your Client ID and Client Secret — copy both.

Enter Credentials in Admin Settings

Go to Admin → Settings → Google Integration:

• Paste your Google Client ID
• Paste your Google Client Secret
• Click Save

Initiate OAuth Connection

As a regular user, go to My Account → Integrations → Google Sheets and click Connect Google Account. You'll be redirected to Google's OAuth screen.

Authorize Access

Sign in with your Google account and click Allow to grant AgentLabs read/write access to your Google Sheets. You'll be redirected back to AgentLabs automatically.

Select Your Spreadsheet

After connecting, you'll see a dropdown to choose which Google Spreadsheet to sync call data to. You can select an existing spreadsheet or create a new one.

Open the Tools Panel in Flow Builder

Go to your flow and open the Tools panel on the left side of the Flow Builder. Find Google Sheets in the list and click Connect. This links the Google account you authorized in Part 2 to the flow.

Assign a Spreadsheet to a Form Node

Inside your flow, open any Form node (the node that collects data from the caller). Go to the Integrations tab within the node settings. Select your connected Google Sheets account from the dropdown and choose which spreadsheet to write data to. Data is written to the sheet each time that form node is completed during a call.

Enable Google Calendar API

1. Go to console.cloud.google.com and select your project
2. Navigate to APIs & Services → Library
3. Search for "Google Calendar API"
4. Click on it and click Enable
5. Wait 1–2 minutes for the API to propagate — attempting to use it immediately may result in a 403 error even after enabling

Update OAuth Consent Screen Scopes

If you're reusing an existing GCP project, add the Calendar scope:

1. Go to OAuth consent screen → Edit App
2. Under Scopes, add: https://www.googleapis.com/auth/calendar
3. Save the changes

Verify OAuth Credentials

Ensure your OAuth credentials (Client ID + Client Secret) are already entered in Admin → Settings → Google Integration. The same credentials are used for both Sheets and Calendar OAuth flows.

Open Appointments Settings

Go to Appointments → Settings tab. You'll see a Google Calendar section showing your current connection status.

Connect Your Google Account

Click Connect Google Calendar. You'll be redirected to Google's OAuth screen. Sign in and click Allow. Once connected, your email address will appear as the connected account.

Enable Auto-Sync

Toggle Auto-sync to Google Calendar on. When enabled, every new appointment and status change is automatically synced to your primary Google Calendar without any manual action.

Create a Webhook Subscription

Navigate to Dashboard → Webhooks and click Add Webhook:

• Enter your HTTPS endpoint URL (HTTP is rejected)
• Select the events you want to receive
• A unique signing secret is generated automatically — copy and store it

Verify Signatures on Your Server

// Node.js — verify incoming webhook signature
const crypto = require('crypto');

function verifyWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}Copy

Go to the Plugin Manager

Log in as admin and navigate to Admin → Settings → Plugins.

Upload the Plugin Zip

Click Upload Plugin and select the plugin zip file. The installer automatically:

• Validates the zip structure and plugin manifest
• Extracts files to the plugins/ directory
• Runs any database migrations included in the plugin
• Triggers a server restart to load the plugin

Verify Plugin is Loaded

After restart, check the server logs for confirmation:

[Plugin Loader] Using compiled JS for 'sip-engine'
[SIP Engine] Plugin registered (v2.0)
[OK] SIP Engine Plugin initializedCopy

Create a SIP Trunk

Users go to My SIP Trunks → Add Trunk:

• Select SIP provider from the dropdown
• Enter SIP host/server (e.g., sip.telnyx.com)
• Enter SIP username and password
• Select engine: ElevenLabs SIP

Import Phone Numbers

Add E.164 format phone numbers (+14155551234) associated with the trunk. Each number is assigned an AI agent for inbound handling.

Test the Connection

Click Test Connection to verify SIP trunk reachability. The system validates hostname format, port range, and DNS resolution.

Get Your OpenAI Project ID

At platform.openai.com, go to Settings → Project → General and copy your Project ID.

Configure in Admin Panel

Go to Admin → Settings → SIP Engine → OpenAI SIP and enter the Project ID.

Set Up OpenAI Webhook

In OpenAI Dashboard → Settings → Project → Webhooks:

• Create a webhook with URL: {APP_URL}/api/openai-sip/webhook
• Event type: realtime.call.incoming
• Copy the Webhook Secret and enter it in the admin panel

Create a Team

Users go to Team in their dashboard and click Create Team. Each user account can have one team.

Define Custom Roles

Create roles with specific permissions per feature section:

• Manager: Full access to all features in the account
• Agent: Can run campaigns and view calls, but not billing
• Viewer: Read-only access across all sections
• Custom: Select exactly which sections and actions (Create/Read/Update/Delete) each role can perform

Invite Team Members

Enter team member email addresses and assign roles. Members receive an invitation and log in with their own credentials.

Create an API Key (User)

Users go to Dashboard → API Keys → Create Key. Configure:

• A descriptive name for the key
• Scope: read-only, write, or full access per resource type
• Optional rate limiting override

Copy the key immediately — it is shown only once.

Authenticate API Requests

curl -H "X-API-Key: your_api_key_here" \
     https://yourdomain.com/api/v1/agentsCopy

Install System Dependencies

# System updates and build tools
sudo apt-get update && sudo apt-get upgrade -y
sudo apt-get install -y build-essential curl git unzip

# Node.js 20.x LTS
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# PM2 process manager
sudo npm install -g pm2

# PostgreSQL
sudo apt-get install -y postgresql postgresql-contrib
sudo systemctl enable postgresqlCopy

Set Up Database

sudo -u postgres psql <<EOF
CREATE DATABASE agentlabs;
CREATE USER agentlabs_user WITH ENCRYPTED PASSWORD 'strong_password_here';
GRANT ALL PRIVILEGES ON DATABASE agentlabs TO agentlabs_user;
ALTER DATABASE agentlabs OWNER TO agentlabs_user;
\q
EOFCopy

Deploy Application Files

sudo mkdir -p /root/agentlabs
cd /root/agentlabs
unzip AgentLabs-v5.3.7.zip -d .
mkdir -p plugins && touch plugins/.gitkeepCopy

Create Production .env

NODE_ENV=production
PORT=5000
APP_URL=https://yourdomain.com
BASE_URL=https://yourdomain.com
DATABASE_URL=postgresql://agentlabs_user:strong_password_here@localhost:5432/agentlabs
SESSION_SECRET=$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")
JWT_SECRET=$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")Copy

Install, Build, and Initialize

npm install
npm run build
npm run db:pushCopy

Launch with PM2

pm2 start npm --name "agentlabs" -- start
pm2 save
pm2 startup  # Run the output command to enable auto-start on rebootCopy