LiveKit docs › Agent Server › Startup modes --- # Server startup modes > Guide to different agent server modes for development, production, and more. ## Overview The Agents SDK includes a CLI interface that makes it easy to start your agent server in various modes. Each mode is optimized for specific use cases and development stages, from local testing to production deployments. Your agent server can be started in the following modes: | Mode | Description | | [`start`](#start-mode) | Production mode with graceful shutdown handling and optimized logging. | | [`dev`](#dev-mode) | Development mode with auto-reload and detailed logging for fast iteration. | | [`console`](#console-mode) | Local, single-session, terminal-based testing. Only available for Python agents. | | [`connect`](#connect-mode) | Single-session, direct connection to a specific LiveKit room for targeted debugging with live participants. | There is also a standalone command, `download-files`, that downloads required runtime assets for plugins. See [Download plugin assets](https://docs.livekit.io/deploy/agents/builds.md#download-plugin-assets) on the Builds and Dockerfiles page. ## Authentication You must set authentication credentials before you start your agent server in order to connect to LiveKit and LiveKit Inference. They can be set in environment variables or passed as command-line arguments. > ℹ️ **Console mode** > > Console mode doesn't use your credentials to connect to LiveKit, but it requires them for LiveKit Inference. Because console mode doesn't accept credentials as command-line arguments, you must provide them in environment variables. | Argument | Description | Environment variable | | `--url` | LiveKit server or Cloud project WebSocket URL | `LIVEKIT_URL` | | `--api-key` | LiveKit API key | `LIVEKIT_API_KEY` | | `--api-secret` | LiveKit API secret | `LIVEKIT_API_SECRET` | ### Set environment variables Run the following [LiveKit CLI](https://docs.livekit.io/reference/developer-tools/livekit-cli.md) command to load your LiveKit Cloud API keys into a `.env.local` file: ```shell lk app env -w ``` The file should look like this: ** Filename: `.env.local`** ```shell LIVEKIT_API_KEY= LIVEKIT_API_SECRET= LIVEKIT_URL=%{wsURL}% ``` ** Filename: `.env.local`** ```shell LIVEKIT_API_KEY= LIVEKIT_API_SECRET= LIVEKIT_URL=%{wsURL}% ``` ## Start mode Start mode runs your agent server in production with proper error handling and graceful shutdown. This mode connects to LiveKit with settings optimized for production deployments. Start mode provides the following features: - **Production logging**: Log level defaults to `info` for clean output. - **Graceful shutdown**: Drains active jobs before shutting down on `SIGINT` or `SIGTERM` signals. - **Production optimizations**: Includes load balancing, overload protection, and pre-warmed idle processes to ensure high availability. To start your agent server in production mode, use the following command: **Python**: ```shell uv run src/agent.py start ``` --- **Node.js**: In Node.js, in order to start your agent server in production mode, you must build using `tsc` before you start: ```shell tsc && node agent.js start ``` #### Graceful shutdown In production mode, when your agent server receives a shutdown signal (such as `SIGTERM` from a container orchestrator or `Ctrl+C`), it drains active jobs before closing: 1. Stops accepting new job assignments. 2. Waits for active jobs to complete (up to `--drain-timeout` in Python). 3. Closes all connections and cleans up resources. 4. Exits with appropriate status code. ### Parameters The following parameters are available in production mode: **Python**: | Parameter | Description | Default | | `--log-level` | Set the logging level (`trace`, `debug`, `info`, `warn`, `error`, `critical`) | `info` | | `--drain-timeout` | Time in seconds to wait for jobs to finish before shutting down | None (waits indefinitely) | --- **Node.js**: | Parameter | Description | Default | | `--log-level` | Set the logging level (`trace`, `debug`, `info`, `warn`, `error`, `fatal`) | `info` | ## Dev mode In `dev` mode, your agent server starts with features optimized for local development, including enhanced logging and automatic code reloading: - **Debug logging**: Log level defaults to `debug` for detailed output. - **Auto-reload**: In Python, auto-reloads when code changes are detected. For Node.js, use `tsx` for automatic TypeScript compilation and reloading. - **Development optimizations**: No graceful shutdown drain period for faster iteration. Start your agent server in dev mode with the following command: **Python**: ```shell uv run src/agent.py dev ``` --- **Node.js**: ```shell tsx agent.ts dev ``` ### Parameters The following parameters are available in dev mode: **Python**: | Parameter | Description | Default | | `--log-level` | Set the logging level (`trace`, `debug`, `info`, `warn`, `error`, `critical`) | `debug` | | `--no-reload` | Disable auto-reload on file changes. | By default, auto-reload is enabled. | --- **Node.js**: | Parameter | Description | Default | | `--log-level` | Set the logging level (`trace`, `debug`, `info`, `warn`, `error`, `fatal`) | `debug` | ## Console mode Available in: - [ ] Node.js - [x] Python Console mode runs your agent server in your terminal without connecting to LiveKit. This single-session mode simulates a full agent session entirely on your local machine for quick testing and debugging during development. Console mode allows you to interact with your agent using text or voice, and offers the following features: - **Audio I/O**: Choose which local audio devices to use for input and output. - **Visual feedback**: Displays audio input using a real-time frequency visualizer. - **Text mode**: Toggle between audio and text-only interaction. - **Session recording**: Record sessions to disk for playback and analysis. > ℹ️ **LiveKit Inference** > > While console mode doesn't use LiveKit for media transport, if you're using [LiveKit Inference](https://docs.livekit.io/agents/models.md#inference), you must have your authentication credentials set as environment variables in order to test your agent. See the [Authentication](#authentication) section for more information. Start your agent server in console mode with the following command: ```shell uv run src/agent.py console ``` You can speak to your agent with text or voice. ### Parameters The following parameters are available in console mode: | Parameter | Description | | `--text` | Interact with your agent using only text input (no audio). You can also toggle between audio and text input using the shortcut `Ctrl+T`. | | `--input-device` | Specify the input device to use for audio input using device ID or name substring. Use `--list-devices` to get the device IDs and names for available input devices. | | `--output-device` | Specify the output device to use for audio output using device ID or name substring. Use `--list-devices` to get the device IDs and names for available output devices. | | `--list-devices` | List all available input and output audio devices on your system. | | `--record` | Record the agent session to disk. If enabled, saves the session to a JSON file named `console-recordings/session-/`. | ### Examples Use these examples to run your agent in console mode with different configurations: List available audio devices: ```shell uv run src/agent.py console --list-devices ``` Run your agent in text-only mode: ```shell uv run src/agent.py console --text ``` Specify input and output devices for audio: ```shell uv run src/agent.py console --input-device "Macbook Pro Microphone" --output-device "External Headphones" ``` Record the session to disk: ```shell uv run src/agent.py console --record ``` ## Connect mode Connect mode starts your agent server with a direct connection to a specific LiveKit room. This single-session mode is useful for testing with live participants or debugging specific room scenarios. **Python**: ```shell uv run src/agent.py connect --room my-test-room ``` Connect to a room with a specific participant identity: ```shell uv run src/agent.py connect --room my-room --participant-identity my-agent-1 ``` --- **Node.js**: ```shell pnpm tsx agent.ts connect --room my-test-room ``` Connect to a room with a specific participant identity: ```shell pnpm tsx agent.ts connect --room my-room --participant-identity my-agent-1 ``` ### Parameters **Python**: | Parameter | Description | Required | | `--room` | Name of the room to connect to. If the room doesn't exist, it's automatically created. | Yes | | `--participant-identity` | Identity to use for the agent participant. Autogenerated if not provided. | No | | `--log-level` | Set the logging level. Valid values are: `trace`, `debug`, `info`, `warn`, `error`, `critical`. Default is `debug`. | No | --- **Node.js**: | Option | Description | Required | | `--room` | Name of the room to connect to. | Yes | | `--participant-identity` | Identity to use for the agent participant. Autogenerated if not provided. | No | | `--log-level` | Set the logging level. Valid values are: `trace`, `debug`, `info`, `warn`, `error`, `fatal`. Default value is `debug` or the value set in the `LOG_LEVEL` environment variable. | No | ## Add scripts in Node.js If you're using Node.js, you can add the following scripts to your `package.json` file to start your agent server in different modes using `pnpm`: ```json { "scripts": { "dev": "tsx agent.ts dev", "build": "tsc", "start": "tsc && node agent.js start", "connect": "tsx agent.ts connect" } } ``` For example, to start the agent in development mode, execute the following command: ```shell pnpm dev ``` --- This document was rendered at 2026-06-07T11:34:13.138Z. For the latest version of this document, see [https://docs.livekit.io/agents/server/startup-modes.md](https://docs.livekit.io/agents/server/startup-modes.md). To explore all LiveKit documentation, see [llms.txt](https://docs.livekit.io/llms.txt).