Deployment management

Overview

Use the LiveKit CLI to configure, deploy, and manage your agent deployments. This guide covers deployment configuration, deploying new versions, rolling back, and understanding cold starts.

Configuration

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

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 and Dockerfiles 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 once they're considered healthy.
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.

Health checks

LiveKit Cloud only removes old agent instances after the new agent's health check endpoint starts passing. This ensures that if the new agent doesn't start correctly or starts slowly, the old agent instances can still serve new traffic.

LiveKit Cloud allows 5 minutes for the health check to start passing for a new agent instance. If you're not seeing requests routed to the new agent version, make sure the prewarm function doesn't take longer than 5 minutes to complete.

Deploy with GitHub Actions

To deploy from CI instead of running lk agent deploy by hand, use the livekit/deploy-action  GitHub Action. Use it to deploy your agent whenever code is pushed to your main branch.

1. Add the following secrets to your GitHub repository (navigate to Settings → Secrets and variables → Actions):

1. Add a workflow file at .github/workflows/deploy.yml that deploys on push.

   The follow example deploys your agent whenever code is pushed to your main branch in the voice-agent directory:

   name: Deploy agent
   on:
     push:
       branches:
         - main
       paths:
         - 'voice-agent/**'
   
   jobs:
     deploy:
       runs-on: ubuntu-latest
       concurrency:
         group: deploy-${{ github.ref_name }}
         cancel-in-progress: true
   
       steps:
         - uses: actions/checkout@v4
   
         - name: Deploy LiveKit Cloud agent
           uses: livekit/deploy-action@v2
           env:
             LIVEKIT_URL: ${{ secrets.LIVEKIT_URL }}
             LIVEKIT_API_KEY: ${{ secrets.LIVEKIT_API_KEY }}
             LIVEKIT_API_SECRET: ${{ secrets.LIVEKIT_API_SECRET }}
             SECRET_LIST: ${{ secrets.SECRET_LIST }}
           with:
             OPERATION: deploy
             WORKING_DIRECTORY: voice-agent

To require manual approval before a deploy, run the job under a GitHub environment  with required reviewers.

Action inputs

The GitHub action accepts the following inputs, set under the with key:

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 the Build (free) plan, production agents can be scaled down to zero replicas after all active sessions end. When a new user connects, the instance does a "cold start" to serve them, which adds 10 to 20 seconds before the agent joins the room. On paid plans (Ship and Scale), production agents stay warm. For more info, see the Quotas and limits guide.

Non-production deployments always scale to zero when idle, on every plan, and cold-start on the next request.