How to Use Console Mode for Local Testing with LiveKit Agents

LiveKit Agents provides a built-in console sub-command that runs agents entirely locally without requiring a LiveKit server, supporting both interactive audio capture and text-based debugging modes.

The livekit/agents repository includes a powerful console mode for local testing that eliminates infrastructure dependencies during development. This feature allows developers to test voice and text agents directly from the terminal using local audio devices or simple text input, making it ideal for rapid iteration before deploying to production.

What Is Console Mode in LiveKit Agents?

Console mode is a local testing environment implemented in livekit-agents/livekit/agents/cli/cli.py using the Typer framework. It creates a self-contained runtime that mimics a LiveKit room connection without actually connecting to a server.

The console provides four primary operational modes:

• Audio mode (default): Captures microphone input, processes it through the agent's STT and LLM pipeline, and plays back synthesized speech through local speakers
• Text mode (--text): Accepts typed text input and prints assistant responses directly in the terminal
• Record mode (--record): Saves complete session artifacts including audio files and transcripts to console-recordings/
• List devices (--list-devices): Enumerates available input and output audio devices with their IDs

Installation and Prerequisites

Before using console mode for local testing, install the package with development dependencies to ensure all STT, TTS, and LLM plugins are available.

Run the installation from the repository root:

make install

This executes uv sync --all-extras --dev, pulling in all optional dependencies required for console operation.

If you plan to use external providers like OpenAI, set the appropriate environment variables:

export OPENAI_API_KEY="sk-..."

The built-in fake_* plugins work without API keys for basic testing.

Running the Console for Local Testing

Invoke the console sub-command using the module path:

python -m livekit.agents.cli console [options]

Audio Mode (Default)

The default audio mode captures from your default microphone and plays responses through default speakers:

python -m livekit.agents.cli console

During operation, the console displays a rich UI showing real-time transcription, processing metrics, and assistant responses.

Text Mode

For environments without audio hardware or for quick debugging, use text mode:

python -m livekit.agents.cli console --text

This disables audio I/O and provides a simple REPL-style interface in the terminal.

Recording Sessions

To capture session artifacts for later analysis:

python -m livekit.agents.cli console --record

Recordings save to console-recordings/session-<timestamp>/, containing individual audio tracks and JSON transcripts.

Listing and Selecting Audio Devices

When default devices are insufficient, enumerate available hardware:

python -m livekit.agents.cli console --list-devices

Then specify devices by ID:

python -m livekit.agents.cli console \
    --input-device 4 \
    --output-device 5

How Console Mode Works Under the Hood

The console implementation centers on the _run_console function in livekit-agents/livekit/agents/cli/cli.py. This function instantiates a singleton AgentsConsole class that manages the local testing lifecycle.

When initialized, the console:

1. Creates a _ConsoleWorker thread that runs the AgentServer from livekit/agents/worker.py in the background
2. Acquires I/O resources through AgentsConsole.acquire_io, constructing ConsoleAudioInput and ConsoleAudioOutput adapters
3. Injects these adapters into the agent's AgentSession (defined in livekit/agents/voice/agent_session.py), bypassing the standard LiveKit room connection

The main loop alternates between _audio_mode and _text_mode based on the AgentsConsole.console_mode state. Audio mode captures PCM data from the microphone, streams it through the STT pipeline, and plays synthesized TTS responses through the output adapter.

Interactive toggling between modes is handled by catching the _ToggleMode exception, typically bound to Ctrl-T during the session.

Graceful shutdown occurs when the process receives SIGINT or SIGTERM, triggering cleanup of the ConsoleWorker thread and release of audio streams.

Summary

• LiveKit Agents provides a built-in console mode for local testing without requiring a LiveKit server connection
• The console supports audio capture, text input, session recording, and device enumeration through Typer CLI options
• Implementation resides in livekit-agents/livekit/agents/cli/cli.py using the AgentsConsole singleton and _ConsoleWorker thread architecture
• Audio I/O is handled through ConsoleAudioInput and ConsoleAudioOutput adapters injected into the standard AgentSession pipeline
• Invoke with python -m livekit.agents.cli console and toggle between modes with Ctrl-T during operation

Frequently Asked Questions

Can I use console mode without a LiveKit server?

Yes. Console mode is specifically designed for local testing without any LiveKit server infrastructure. The AgentsConsole class in cli.py creates a local runtime that simulates room connections by injecting console-based audio and text adapters directly into the agent's session, bypassing the standard WebRTC room protocol entirely.

How do I switch between audio and text mode during a session?

Press Ctrl-T during an active console session to toggle between audio and text modes. This keyboard shortcut raises a _ToggleMode exception that the main loop catches in _run_console, switching the AgentsConsole.console_mode state between "audio" and "text" and reinitializing the appropriate I/O handlers without restarting the agent process.

Where are console recordings saved?

When using the --record flag, session recordings are saved to a directory named console-recordings/session-<timestamp>/ relative to your current working directory. This directory contains individual audio files for each track and JSON transcript files capturing the full conversation history, as implemented in the AgentsConsole class's recording logic within cli.py.

What audio formats does console mode support?

Console mode captures and plays PCM audio using the ConsoleAudioInput and ConsoleAudioOutput adapters defined in the CLI module. The implementation uses standard system audio interfaces (PortAudio via PyAudio on most platforms) to stream raw PCM data to and from the agent's STT and TTS pipelines, supporting whatever sample rates and channel configurations your local hardware and the active plugins require.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}