Install SPX Voice With Your AI Agent (and Fix Any Error)

SPX Voice is an open-source platform for building and deploying conversational voice agents. You get a workflow-builder dashboard with telephony and WebRTC, powered by runtimes like Pipecat and LiveKit.

This guide is for web coders and vibe coders. You don’t need to understand every line. You’ll install SPX Voice by letting your AI coding agent (Cursor, Claude Code, VS Code + Copilot, and so on) do the heavy lifting. More importantly, you’ll learn the real skill: how to prompt your agent to fix any error, and how to use screenshots so you never get stuck.

▶️ Watch the full video above first. It walks through the whole install from start to finish. The steps here follow the video, so you can copy the commands as you go.

What you’ll need

• Docker Desktop installed and running (download)
• Git installed
• An AI coding agent: Cursor, Claude Code, or VS Code + Copilot
• These local ports free: 3010, 8000, 5432, 6379, 9000, 9001, 2000

Don’t have Docker or Git? Ask your agent: “How do I install Docker Desktop and Git on Windows 11 (or macOS)? Give me the exact steps.”

Step 1: Get the project

Clone the repo and move into the folder:

git clone https://github.com/SorrowSFR/spx-voice.git
cd spx-voice

Step 2: Open it in your AI agent

Open the spx-voice folder in your coding agent (Cursor → File → Open Folder; Claude Code → run it inside the folder; VS Code → Open Folder).

This is important: opening the whole folder gives the agent context of the entire codebase, so when something breaks it can actually find and fix it.

Step 3: Start SPX Voice

The project ships with a start script that launches everything with Docker.

macOS / Linux:

bash start.sh

Windows (PowerShell):

.\start.ps1

The first run downloads the Docker images, so give it a few minutes. When it finishes, open http://localhost:3010 in your browser.

Nothing loads yet? That’s normal on the first boot while services start. Wait a minute and refresh. If it’s still broken, move to the next step. This is where the real skill comes in.

Step 4: Hit an error? Here’s how to prompt your agent

This is the most important step. When something breaks, don’t panic and don’t guess. Copy the full error and give your agent context. Paste this template into your agent’s chat:

I'm installing the SPX Voice project (an open-source voice-agent platform that
runs on Docker).
My OS: [Windows 11 / macOS / Linux]
I ran this command: [paste the exact command]
I got this error:

[paste the FULL error output here, all of it]

What is causing this, and what are the exact steps/commands to fix it?
Explain briefly, then give me the commands to run.

A few rules make your agent far more useful:

• Paste the WHOLE error, not just the last line. The cause is often higher up.
• Say your OS and the exact command you ran.
• Ask for exact commands, not theory.
• After it answers, run the fix, then paste the new output back so it can confirm it worked or keep going.

Step 5: Use screenshots when the problem is on screen

Sometimes the problem is visual: the dashboard looks wrong, a button does nothing, or the browser throws an error. In those cases a screenshot tells your agent far more than words.

How to paste a screenshot into your agent: in Cursor, Claude Code and Copilot Chat you can paste an image straight into the chat box with Ctrl/Cmd + V.

• Take the screenshot: Windows = Win + Shift + S, macOS = Cmd + Shift + 4.
• Capture the whole window, including the address bar and any red errors.
• Open the browser console for more detail: press F12 → Console tab → screenshot anything in red.

Then prompt:

Here's a screenshot of what I see at http://localhost:3010 (and the browser
console). I expected [what], but I see [what].
What's failing, and how do I fix it?

Step 6: Feed it the logs

Most Docker problems show up in the container logs. Grab them and hand them over:

docker compose logs --tail=100

Then paste:

Here are the last 100 lines of my SPX Voice Docker logs. Find what's failing and
tell me the exact fix:

[paste the logs here]

Handy commands your agent may ask you to run:

docker compose ps        # see which services are running
docker compose down      # stop everything
docker compose down -v   # stop AND wipe data for a clean restart

Step 7: Still stuck? Join the community

Some errors are specific to your machine or setup. Don’t waste hours stuck on your own. Drop your question (and that screenshot) in our WhatsApp community, and we and other builders following the same video will help you get it running.

👉 Join the SPX WhatsApp community

Once SPX Voice is up at http://localhost:3010, you’re ready to start building voice agents. Nice work. 🎙️