Goal: Prove this machine can reach Deepgram and move audio in both directions, before getting too deep.
You'll learn
- Why
DEEPGRAM_API_KEYis the only credential this course needs - That a working key and a working agent are two different questions
- What a working microphone looks like from the browser's side of the glass
- The two browser capabilities everything after this depends on
Three commands and a browser page:
uv sync
cp .env.example .env # then paste your key in
uv run steps/01-setup/main.pyYou should end up with four OK lines in the terminal, a page with five green rows, and a tone
you actually hear. The rest of this module is what each of those proves, and what to do when one
of them isn't OK.
Voice work fails in a specific, predictable order: the API key is wrong, the browser never got microphone permission, or you are serving the page from somewhere the browser refuses to trust with a microphone at all. Each of those produces a confusing error twenty minutes later, tangled up in WebSocket code where it looks like a Deepgram problem. Running the checks now turns all three into a one-line answer.
This module also triggers your browser's microphone permission prompt. The audio half of this check runs in a browser page, because that is where the rest of the course's audio runs. Be sure to approve the browser's request to access your microphone. If you need to change audio devices at any point, you may need to repeat this process by clicking the lock icon from the browser's address bar.
There are two separate questions here, and the check answers them separately. Is my key good? is a single authenticated HTTP call. Can I actually run an agent? is a WebSocket handshake against three named models, which can fail for reasons that have nothing to do with your key, a proxy in the way, or a model that isn't served where you're connecting. A check that only validated the key would let both of those ambush you in Module 2.
1. Install the dependencies. From the repository root:
uv syncOne virtual environment serves every module in this course. You run this once.
If your terminal answers command not found: uv, install uv first from
docs.astral.sh/uv/getting-started/installation,
then open a fresh terminal and run uv --version to confirm it's on your PATH.
2. Create your .env file.
cp .env.example .envOpen .env and paste in your Deepgram API key. If you don't have one yet, sign up free at console.deepgram.com, open API Keys, and create a new key. Copy it right away: the Console only shows it once.
That key is the only credential you need. The agent you build uses OpenAI's gpt-4o-mini as its brain, but Deepgram brokers that call, so no OpenAI account, no second key, no second bill.
Deepgram applies $200 in credit to new accounts automatically. This course costs well under a dollar, so you'll have plenty left to keep building afterward.
.env also holds DEEPGRAM_REGION, which decides where Deepgram processes your audio: global by default, or eu, au, or in for the endpoints that keep it inside those geographies. Leave it blank: every module works on global, no code in this course names a region, and if you later need your audio to stay inside the EU, Australia, or India, moving it is this single line. Northwind Clinic's real-world constraint that health information stays in one environment is exactly what this line is for. One limit to know: the region covers speech-to-text and text-to-speech, and in the EU the managed LLM call too. In Australia and India the agent's think step is still processed outside the region. To keep it in-region there, point think.endpoint at an LLM you host in that geography, as Appendix A shows; that call is then billed by your LLM provider, not by Deepgram. For full residency, also set mip_opt_out=True on the agent's Settings message, so your data stays out of Deepgram's Model Improvement Program.
3. Run the check.
uv run steps/01-setup/main.pyIt checks your key in the terminal, briefly starts the agent you're about to build, then opens a page. Press Run the audio checks, allow the microphone when your browser asks, speak when it tells you to, and listen for the tone. Ctrl+C in the terminal when you're done.
The check verifies the models are connecting over WebSockets without needing to send audio bytes.
The terminal shows:
[ OK ] DEEPGRAM_API_KEY found (84de...c2db)
[ OK ] Deepgram accepted the key (project: Your Project)
[ OK ] Region: global (wss://agent.deepgram.com/v1/agent/converse)
[ OK ] Agent started (flux-general-en + gpt-4o-mini + flux-alexis-en)
and the page shows five green rows:
OK Secure context http://127.0.0.1:8000 is a secure context
OK Audio support AudioWorklet and getUserMedia are available
OK Deepgram API key Accepted by Deepgram (project: Your Project)
OK Microphone Heard you (peak 0.34).
OK Speaker Played a tone -- you should have heard it
Before Module 2, all three of these have to be true:
- Four
OKlines in the terminal, includingAgent startedwith all three model names. Key plus pipeline. - Five
OKrows on the page, and you heard the tone. Not "the row says OK", heard it. - The microphone row reports a peak above roughly
0.10. A peak near zero means the browser opened a device that isn't picking you up, which looks like success and behaves like silence.
If any row is not OK, find it in Stuck? below. Do not carry a failing row into Module 2:
every symptom here gets harder to read once there's WebSocket code around it.
One note is allowed. If the microphone row ends with Echo cancellation is off, keep going, wear
headphones and expect Module 5 to be noisier than it should be.
DEEPGRAM_API_KEY is not set. You created .env but the key landed in the wrong place, or the file is named .env.txt. The file belongs in the repository root, next to pyproject.toml.
Deepgram rejected the key. Almost always a truncated paste or a trailing space. Copy it again from the console. This check makes a real authenticated call rather than testing that the string is non-empty, which is why a truncated key surfaces here instead of in Module 2.
DEEPGRAM_REGION=... is not a Deepgram hosting location. A typo in .env. The options are global, eu, au, and in; blank means global. The check refuses to guess, because a typo that quietly fell back to global would still work and would still be sending your audio to the wrong continent.
Could not open the agent connection. The key is fine and something is between you and Deepgram. Usually a proxy or firewall: this needs an outbound wss:// connection to the address printed on the Region line above it. Corporate VPNs and guest wifi are the usual suspects; a phone hotspot is the fastest way to confirm it.
The agent refused these settings. Nothing is wrong with your machine. Deepgram doesn't serve one of the three models where you're connecting. The error names which one, and model availability differs by region. If you set DEEPGRAM_REGION yourself, set it back to blank and run again: that resolves almost every case. If you are required to stay in a specific region, the fix is to change that one model name in every module, and the voice catalogue lists the alternatives.
Secure context fails. You opened the page on a LAN address like 192.168.1.5:8000. Browsers only hand out microphone access on a secure context, and a bare IP is not one. Use http://127.0.0.1:8000, the address the terminal printed. This is the most common environment failure in this course, and the symptom is a Connect button that stays disabled.
Permission denied. Your browser is blocking the microphone for this site. Click the icon at the left of the address bar, allow it, and press the button again. On macOS also check System Settings → Privacy & Security → Microphone and confirm your browser is enabled there: note that it is the browser that needs permission now, not the terminal.
Opened, but heard almost nothing. Two usual causes: you're muted, or the browser picked the wrong input. Change the input in your OS sound settings, reload the page, and try again.
Echo cancellation is off at the end of the microphone row. Your browser did not grant it. Everything still works; wear headphones, and expect Module 5 to be noisier than it should be.
Browser gave 48000 Hz instead of 24000 Hz. Mostly iOS Safari, and the run still succeeds: the audio worklets resample instead. Quality drops a little and nothing else changes.
Bluetooth headphones behaving strangely. Many headsets expose a low-quality mono profile when their microphone activates, and some renegotiate the sample rate mid-session, and a few then fail to open at all. Reconnect, or switch to wired. Wired headphones are the reliable choice here, and they also spare you the speaker-feeding-microphone loop in Module 5.
The agent talks to itself. Laptop speakers feeding the laptop microphone, past the echo canceller. Rarer than it used to be, which makes it more confusing when it happens. Headphones, or turn the volume down. The microphone row above tells you whether the browser actually granted echo cancellation: if it did not, the row ends with Echo cancellation is off.
Nothing opens. Some environments have no browser to open. The terminal prints the URL; open it yourself, or pass --no-open to stop it trying.
Every module also runs against the system microphone and speaker through PortAudio, with --local. If you intend to work that way, check it now:
uv run steps/01-setup/main.py --localCould not query audio devices on Linux. Install ALSA's userspace pieces and the PulseAudio plugin:
sudo apt install -y libportaudio2 libasound2-plugins alsa-utilsWSL routes audio through PulseAudio, but PortAudio only looks for ALSA. Bridge the two:
sudo apt install -y libasound2-plugins
cat > ~/.asoundrc <<'EOF'
pcm.!default { type pulse }
ctl.!default { type pulse }
EOFWSL audio used to be the single most common environment failure here. You can now sidestep it entirely: drop --local and the audio goes through your Windows browser instead, which needs none of the above.
- One credential.
DEEPGRAM_API_KEYcovers the LLM too, because Deepgram brokers that call. - A good key and a working agent are different questions. The check answers both, separately, so a proxy or an unavailable model can't masquerade as a bad key later.
- The browser is the microphone and the speaker. It needs a secure context (
127.0.0.1, never a LAN address) plusgetUserMediaandAudioWorklet. - Region is one line, and the only thing that decides where audio is processed.
Open your browser's dev tools (F12) on the check page and watch the console while you run it. You'll see the sample rate the browser actually gave you. Then look at the Network tab: the browser fetches worklets.js and hands it to the audio thread, making it the only file in this course that does not run on the main thread.
With your environment confirmed working, you can open a connection to the Voice Agent API and start describing the agent you want to build.