Local development.

[ahmed-rezk-dev]

Hi everyone! I don't have any issues running the project on Docker. My problem occurs when running it on localhost, as I want to experiment with the project and potentially extend it as a full-stack JavaScript developer while learning more about Python.

In the local setup, STT (speech-to-text) works perfectly—mlx-audio transcribes speech (logs show 🗣️ STT), and the connection to http://localhost:8001 is fine. However, frontend chat messages remain empty. The agent generates and speaks responses, but these aren't published as chat messages to LiveKit. The frontend's useSessionMessages hook expects chat messages (e.g., for agent responses), but receives none.

In contrast, the full Docker setup (start-apple.sh) works because everything is containerized and integrated. In the containerized environment (docker-compose.apple.yaml), the agent might implicitly send chat messages due to unified networking/config, or additional integrations (e.g., n8n workflows) trigger chat publishing. The local development split setup lacks this integration.

Details:

• STT Success: mlx-audio runs locally and transcribes speech, confirming the connection to http://localhost:8001 is working.
• Chat Message Issue: The agent produces responses and speaks them, but doesn't publish them as chat messages to LiveKit. The frontend's useSessionMessages hook expects these messages (e.g., for agent responses), but gets nothing.
• Why Docker Works: In the containerized setup (docker-compose.apple.yaml), unified networking/config may cause the agent to implicitly send chat messages, or integrations like n8n workflows trigger publishing. Local development lacks this.
• Frontend Behavior: Chat input is enabled (supportsChatInput: true), but agent responses are voice-only. The chat transcript shows user messages but no agent text.
  Any insights or fixes would be greatly appreciated! Thanks. 😊

[cmac86]

Hi @ahmed-rezk-dev

A few clarifying questions about your local dev setup:

1. What command are you using to run the agent locally? (uv run voice_agent.py dev?)
2. What's still running in Docker vs what's running natively?
3. When you hear the agent speak, is the audio coming through your browser (frontend) or through the console?
4. What's your LIVEKIT_URL pointing to in local dev?

If the TTS audio is playing through console instead of the browser, the agent might not be connected to a LiveKit room at all - which would explain why transcriptions don't show up in the frontend.

[ahmed-rezk-dev]

Hi @cmac86 thank you for taking the time to answer that.

1. Yes I run it using the command you mentioned.
2. MLX running locally for STT, TTS. The only server runing on docker is the Livekit.
3. I hear the voice on the broswer with the voice animation working as well and the agent can heat me as well. But nothing showing up on the messages box is working.
4. http://localhost:7880 and I also tried replacing localhost with the ip.

[cmac86]

Hi @ahmed-rezk-dev! Interesting - chat transcripts seem to just work by default typically.

First: Check Your Version

Can you run this and share the output?

uv pip show livekit-agents

The project specifies livekit-agents~=1.3 in pyproject.toml, so you should have version 1.3.x installed. If you have a different version, that could explain the behavior difference.

There's a setting in LiveKit Agents to explicitly enable transcription:

from livekit.agents.voice import RoomIOOptions

await session.start(
    room=ctx.room,
    agent=assistant,
    room_io_options=RoomIOOptions(
        transcription_enabled=True,
    ),
)

However, this has never been needed in CAAL - transcription works by default. If your version differs from what's expected, the default behaviour might have changed between versions. I might have to add this to the code to explicitly turn on transcription.

Also, if you’re running directly with python voice_agent.py dev this might be using a different version of LiveKit-agents. Should be ran with uv run voice_agent.py dev

Thanks,
cmac