Deploying to LiveKit Cloud

Overview

Deploy your agents to LiveKit Cloud to run them on LiveKit's global network and infrastructure. LiveKit Cloud provides automatic scaling and load balancing, ensuring capacity for new sessions up to the limits of your plan. Deploy your agent with a single LiveKit CLI command.

For deployments to other environments, see Deploying to custom environments.

Quickstart

Follow these steps to deploy your first agent to LiveKit Cloud.

Prerequisites

This guide assumes that you already have:

• LiveKit CLI version 2.5 or later
• A LiveKit Cloud project
• A working agent. Create one using the Voice AI quickstart or one of the following starter templates:

Python starter template

A ready-to-deploy voice AI agent built with Python.

livekit-examples/agent-starter-python

Node.js starter template

A ready-to-deploy voice AI agent built with Node.js.

livekit-examples/agent-starter-node

Deploy your agent

Use the following steps with the LiveKit CLI to deploy your agent.

1. Navigate to your project directory:

   cd your-agent-project

2. Authenticate with LiveKit Cloud:

   lk cloud auth

   This opens a browser window to link your LiveKit Cloud project to the CLI. If you've already authenticated and have linked projects, use lk project list to list all linked projects. Then, set the default project for agent deployment with lk project set-default "<project-name>".

3. Deploy your agent:

   lk agent create

   This registers your agent with LiveKit Cloud and assigns a unique ID. The ID is written to a new livekit.toml file along with the associated project and other default configuration. If you don't already have a Dockerfile, the CLI creates one for you.

   Next, the CLI uploads your agent code to the LiveKit Cloud build service, builds an image from your Dockerfile, and then deploys it to your LiveKit Cloud project. See the Builds guide for details on the build process, logs, and templates.

Your agent is now deployed to LiveKit Cloud and is ready to handle requests. To connect, use the Agent Playground, custom frontend, or telephony integration.

Monitor status and logs

Use the CLI to monitor the status and logs of your agent.

1. Monitor agent status:

   lk agent status

   This shows status, replica count, and other details for your running agent.

2. Tail agent logs:

   lk agent logs

   This shows a live tail of the logs for the new instance of your deployed agent.

Deploying new versions

To deploy a new version of your agent, run the following command:

lk agent deploy

LiveKit Cloud builds a container image that includes your agent code. The new version is pushed to production using a rolling deployment strategy. The rolling deployment allows new instances to serve new sessions, while existing instances are given up to 1 hour to complete active sessions. This ensures your new version is deployed without user interruptions or service downtime.

When you run lk agent deploy, LiveKit Cloud follows this process:

1. Build: The CLI uploads your code and builds a container image from your Dockerfile. See Builds for more information).
2. Deploy: New agent instances with your updated code are deployed alongside existing instances.
3. Route new sessions: New agent requests are routed to new instances.
4. Graceful shutdown: Old instances stop accepting new sessions, while remaining active for up to 1 hour to complete any active sessions.
5. Autoscale: New instances are automatically scaled up and down to meet demand.

Rolling back

You can quickly rollback to a previous version of your agent, without a rebuild, by using the following command:

lk agent rollback

Rollback operates in the same rolling manner as a normal deployment.

Cold start

On certain plans, agents can be scaled down to zero replicas. When a new user connects to the agent, the instance does a "cold start" to serve them. This can take a little longer than normal to connect to the user. For more info, see the Quotas and limits guide.

Regions

Currently, LiveKit Cloud deploys all agents to us-east (N. Virginia). More regions are coming soon.

Dashboard

The LiveKit Cloud dashboard provides a view into the status of your deployed and self-hosted agents.

• Realtime metrics: Monitor session count, agent status, and more.
• Error tracking: Identify and diagnose errors in agent sessions.
• Usage and limits: Track usage, billing, and limits.

Configuration with livekit.toml

The livekit.toml file contains your agent's deployment configuration. The CLI automatically looks for this file in the current directory, and uses it when any lk agent commands are run in that directory.

[project]
  subdomain = "<my-project-subdomain>"

[agent]
  id = "<agent-id>"

To generate a new livekit.toml file, run:

lk agent config

Additional resources

The following guides cover additional topics for deploying and managing your agents in LiveKit Cloud.