🍳 Installation Now that you have your ingredients ready, let’s install Voiceblox.
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:
Press Command (⌘) + Space to open Spotlight Search.
Type Terminal and press Enter .
Ubuntu / Debian: Press Ctrl + Alt + T .Or search for Terminal in your applications menu.
Press the Windows key , type PowerShell , and click Windows PowerShell .
Alternatively, press Windows key + R , type powershell, 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 Git Git is the tool used to download the Voiceblox source code.
Check if Git is already installed
If you see a version number — skip to Step 3.
If you see command not found — install it:
Don’t have Homebrew? Install it first:
/bin/bash -c "$( curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
sudo apt-get install -y git
Or download the installer from git-scm.com . After installation, close and reopen your terminal.
Step 3 — Download Voiceblox In your terminal, run:
git clone https://github.com/voiceblox-ai/voiceblox.git cd voiceblox
This downloads the project into a folder called voiceblox and moves you into it.
Step 4 — Choose how to run it 🐳 Docker (recommended)
💻 Without Docker
Docker is the easiest way to run Voiceblox — no need to install Node.js or any other dependencies. Check if Docker is already installed Install Docker brew install --cask docker
Don’t have Homebrew? Install it first:
/bin/bash -c "$( curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
After installation, open the Docker app from your Applications folder to start the Docker engine. sudo apt-get update sudo apt-get install -y docker.io docker-compose-plugin sudo usermod -aG docker $USER
Log out and log back in for the group change to take effect. For other distributions, see Docker’s official install guide .
winget install Docker.DockerDesktop
After installation, open Docker Desktop and wait until the Docker engine is running (you should see the Docker icon in your system tray).
Check if Docker is running Docker needs to be running before you can start the project. Check with:
If you see system information — Docker is running, continue below.
If you see Cannot connect to the Docker daemon — open the Docker Desktop app (macOS/Windows) or start the service with sudo systemctl start docker (Linux), then try again.
Start the project Inside the voiceblox folder, run: docker compose up --build
This builds the Docker images and starts the project. Two services start at once:
The app — open your browser at http://localhost:3000 The agent worker — connects to your LiveKit server and handles voice sessions in the background Stop the project To stop everything, go back to the terminal and press Ctrl + C , then run: If you prefer to run Voiceblox without Docker, you’ll need Node.js and pnpm. Install Node.js Node.js is the engine that runs Voiceblox. You need version 20 or newer . Check if Node.js is already installed
If you see something like v20.x.x or higher — you’re all set, skip to Install pnpm .
If you see command not found or a version below 20 — follow the instructions below.
Don’t have Homebrew? Install it first:
/bin/bash -c "$( curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Confirm it worked: Run the following commands one at a time: curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs
Confirm the installation:
Other Linux distributions: See NodeSource’s guide for RPM-based systems (Fedora, CentOS, etc.). Open PowerShell and run: winget install OpenJS.NodeJS.LTS
If winget is not available, download the installer directly from nodejs.org and run the .msi file.
After installation, close and reopen PowerShell , then confirm: Install pnpm pnpm is the package manager Voiceblox uses.Check if pnpm is already installed
If you see a version number — you’re all set, skip ahead.
If you see command not found — install it:
Confirm it worked: Install dependencies Inside the voiceblox folder, install all required packages: This may take a minute or two. Wait until it finishes before moving on. Start the app Run the development server: 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 5 — Enter Your API Keys When you open the app for the first time, it will ask you for your API keys — this is where you paste the ingredients you collected earlier.
The setup dialog appears automatically on first launch
Paste your Anthropic API Key and Deepgram API Key (if you have one)
Click the ⚙️ Settings button in the toolbar to add your LiveKit credentials (URL, API Key, API Secret)
The app saves everything automatically — no need to edit any files manually .
Docker users: The agent worker reads keys at startup. If you add keys for a new provider while the containers are running, restart the agent with docker compose restart agent for it to pick them up.
You’re all set! Time to build your first agent.
🎨 Build Your First Agent Next step: create a voice agent on the canvas.
