This page is for operators who want to run their own Voice.GradientFlow. If you use a hosted workspace, you do not need it: start with Build your first agent.

​
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 Git

Git is the tool used to download the Voice.GradientFlow 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:

​
Step 3: Download Voice.GradientFlow

In your terminal, run:
This downloads the project into a folder called voice.gradientflow and moves you into it.

​
Step 4: Install Docker

The media server and its message bus always run in Docker, even when you run the app and worker natively. There is no way to run Voice.GradientFlow without it.

​
Check if Docker is already installed

​
Install Docker

Don’t have Homebrew? Install it first:
After installation, open the Docker app from your Applications folder to start the Docker engine.

​
Check if Docker is running

  • 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.

​
Step 5: Install Node.js and pnpm

The web app runs on your machine with Node.js, not in a container. You need version 22 or newer.

​
Check if Node.js is already installed

  • If you see v22.x.x or higher, skip to Install pnpm.
  • If you see command not found or a lower version, follow the instructions below.
Confirm it worked:

​
Install pnpm

If you see command not found:

​
Step 6: Configure the server

Copy the example environment file and fill it in:
At minimum you need:
  • the media server address and credentials. For the local stack the address is ws://localhost:7880, and the key and secret can be any two strings you choose; the media server container reads the same two values;
  • a password for the message bus;
  • a session secret and the public address of the app (http://localhost:3000 locally);
  • a key for the AI builder’s provider, and keys for the model, voice and hearing providers your agents will use.
Provider keys you set here apply to every user and to published agents. The full list, with what each one does, is in Environment variables.
Linux: the app writes published-agent snapshots with group-only read permission. Set the group id variable listed under Storage in Environment variables to the output of id -g so the worker container can read them.

​
Step 7: Start it

Two terminals, both inside the voice.gradientflow folder. Terminal 1: media server, message bus and the agent worker
The first build downloads the worker’s dependencies and takes a few minutes. Leave this running. Terminal 2: the web app
When you see Ready on http://localhost:3000, open http://localhost:3000, create an account and sign in with that email and password (Google sign-in works too once its keys are set).

​
After changing .env

The worker container only reads .env at start. Recreate it after you add or change a key:
Restart pnpm dev for the app.

​
Stop the project

Press Ctrl + C in both terminals, then:
To work on the worker’s Python code with auto-reload, run it natively instead of in Docker: see Python Worker.
You’re all set! Time to build your first agent.

Build your first agent

Open the builder and create a voice agent on the canvas.