Skip to main content

​
Quick Start

This guide walks you through every step from a blank computer to a running voice agent. Each step explains not just what to do, but why.

​
Step 1 — Open the Terminal

The terminal is a text window where you type commands. Here’s how to open it on your operating system:
  1. Press Command (⌘) + Space to open Spotlight Search.
  2. Type Terminal and press Enter.
Every command in this guide should be typed (or pasted) into the terminal and confirmed with the Enter key.

​
Step 2 — Install Node.js

Node.js is the engine that runs Voiceblox. You need version 20 or newer.

​
Check if Node.js is already installed

node --version
  • If you see something like v20.x.x or higher — you’re all set, skip to Step 3.
  • If you see command not found or a version below 20 — follow the instructions below.
Homebrew is the easiest package manager for macOS. If you don’t have it yet, install it first:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Follow the on-screen instructions. You may be asked for your computer password — this is normal.
Once Homebrew is installed, install Node.js:
brew install node@20
Confirm it worked:
node --version

​
Step 3 — Install pnpm

pnpm is the package manager Voiceblox uses to install its dependencies.

​
Check if pnpm is already installed

pnpm --version
  • If you see a version number — skip to Step 4.
  • If you see command not found — install it:
npm install -g pnpm
Confirm it worked: 
pnpm --version

​
Step 4 — Install Git

Git is the tool used to download the Voiceblox source code.

​
Check if Git is already installed

git --version
  • If you see a version number — skip to Step 5.
  • If you see command not found — install it:
brew install git

​
Step 5 — Download Voiceblox

In your terminal, run: 
git clone https://github.com/voiceblox/voiceblox.git
cd voiceblox
This downloads the project into a folder called voiceblox and moves you into it.

​
Step 6 — Install Dependencies

Inside the voiceblox folder, install all required packages: 
pnpm install
This may take a minute or two. Wait until it finishes before moving on.

​
Step 7 — Start the App

Run the development server: 
pnpm dev
When you see a message like Ready on http://localhost:3000, open your web browser and go to: http://localhost:3000 To stop the server at any time, go back to the terminal and press Ctrl + C.

​
Step 8 — Configure API Keys

When you open the app for the first time, it will ask you for two essential API keys:
KeyWhat it doesWhere to get it
Anthropic API KeyPowers the AI Builder — describe your agent in plain language and it builds the flow for youplatform.claude.com/settings/keys
Deepgram API KeyEnables voice input in the builder — speak your prompts instead of typingconsole.deepgram.com
The app saves these keys automatically — no need to edit any files manually. For additional provider keys (LiveKit, OpenAI, ElevenLabs, etc.), use the ⚙️ Settings button inside the app once it’s running.
To run a live voice session in the Test Panel, you also need LiveKit credentials. Get them for free at cloud.livekit.io.

​
Build Your First Agent

Once the app is running, here’s how to build a simple voice agent:
1

Add a Framework node

Drag LiveKit from the sidebar (Framework category) onto the canvas. This is the central node every flow needs.
2

Add component nodes

Drag an LLM, TTS, STT, and Persona node onto the canvas. Connect each one to the Framework node — they auto-route to the correct handle.
3

Configure the Persona

Click the Persona node and fill in the Agent Name and Persona (system prompt) fields — e.g., “You are a friendly customer support agent.”
4

Build the conversation flow

Add a Start node and connect it to the Framework node’s output. Then add a Burst node, then an End node. Chain them: Start → Burst → End.
5

Set the opening line

Click the Start node and set the Command to your opening line (e.g., Hello! How can I help you today?). Enable Is Literal to speak it verbatim instead of generating it.
6

Test it

Click Test in the top bar, then Start Session. Allow microphone access when prompted and start talking to your agent.

​
Or use the AI generator

Instead of building manually, describe your agent in plain language:
  1. Click the AI button in the toolbar
  2. Type something like: Build a customer support agent with a greeting, a triage question, and two branches: billing and technical support
  3. The AI generates the full flow and applies it to the canvas automatically

​
Docker alternative

If you already have Docker installed, you can skip Steps 2, 3, and 6 above. Inside the voiceblox folder, run: 
pnpm docker:up
This starts two services:
  • The app — open http://localhost:3000 to use the builder
  • The agent worker — connects to your LiveKit server and handles voice sessions in the background
To stop everything: 
pnpm docker:down
Don’t have Docker? Download it for free from docker.com/get-started.

​
Next steps

API Keys

Full reference for every supported provider key.

Node Overview

Learn about all available node types.

AI Generation

Generate flows from natural language.

Environment Variables

Complete environment variable reference.