# How to Use Console Mode for Local Testing with LiveKit Agents

> Master local testing with LiveKit Agents console mode. Run agents without a LiveKit server, enabling interactive audio and text debugging for efficient development.

- Repository: [LiveKit/agents](https://github.com/livekit/agents)
- Tags: how-to-guide
- Published: 2026-03-06

---

**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`](https://github.com/livekit/agents/blob/main/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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

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

```

Then specify devices by ID:

```bash
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`](https://github.com/livekit/agents/blob/main/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`](https://github.com/livekit/agents/blob/main/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`](https://github.com/livekit/agents/blob/main/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`](https://github.com/livekit/agents/blob/main/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`](https://github.com/livekit/agents/blob/main/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`](https://github.com/livekit/agents/blob/main/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.