Skip to main content
IntroductionBuild AgentsAgent FrontendsTest & EvaluateTelephonyRoboticsWebRTC TransportManage & DeployReferences
XYouTubeSlack

Deploy agents

Reference for the LiveKit CLI commands that create, deploy, promote, and roll back agents on LiveKit Cloud.

On this page

Overview Working directoryProject and agent identificationTargeting a deploymentCreate Examples Deploy Examples Promote Examples Rollback Examples Versions Examples Delete Examples Config Generate Dockerfile Examples

Overview

Use these commands to create, deploy, promote, and roll back agents on LiveKit Cloud. To check status, stream logs, and manage secrets, see Manage deployed agents. To connect agents to private services in AWS or Azure, see Private links. To install the CLI, see Install the CLI.

Working directory

Commands use the current directory by default. To use another, pass it as the first argument:

lk agent deploy ~/my-agent

Project and agent identification

The CLI uses the project and agent from livekit.toml in the working directory. Without one, it uses the default project, and commands that act on an existing agent take --id or prompt you to pick an agent.

Targeting a deployment

The create, deploy, promote, logs, and delete commands accept --deployment NAME (alias -d) to target a non-production deployment. Omit it to target production. Invalid names are rejected rather than falling back to production.

The status, versions, and list commands show a deployment column instead.

Create

Create a new agent from the working directory, which must not already have a livekit.toml. The CLI creates a Dockerfile if there isn't one.

lk agent create [options] [working-dir]

Options for create:

  • --region REGION: Region code. If unset, the CLI prompts you.
  • --deployment NAME (alias -d): Deployment to create the agent in. Defaults to production.
  • --secrets KEY=VALUE: Secret to inject as an environment variable. Repeatable. Takes precedence over --secrets-file.
  • --secrets-file FILE: File of KEY=VALUE secrets, one per line.
  • --secret-mount FILE: File to load as a file-mounted secret.
  • --ignore-empty-secrets: Skip empty values in a secrets file instead of failing.
  • --attribute KEY=VALUE: Attribute to record on the new version. Repeatable. Takes precedence over --attributes.
  • --attributes JSON: JSON object of string attributes, inline or as a file path. Use - to read from stdin.
  • --no-default-attributes: Don't record the git_commit, git_branch, and git_tree attributes the CLI adds in a git repository.
  • --config FILE: Name of the configuration file to create. Default: livekit.toml.
  • --silent: Don't prompt for confirmation. Default: false.

Examples

Create an agent in us-east with secrets inline and from a file:

lk agent create \
  --region us-east \
  --secrets OPENAI_API_KEY=sk-xxx \
  --secrets-file ./secrets.env

Deploy

Build and deploy a new agent version from the working directory, which must have a livekit.toml and Dockerfile.

lk agent deploy [options] [working-dir]

Options for deploy:

  • --id ID: Agent ID.
  • --deployment NAME (alias -d): Deployment to deploy to. Defaults to production.
  • --secrets KEY=VALUE: Secret to inject as an environment variable. Repeatable. Takes precedence over --secrets-file.
  • --secrets-file FILE: File of KEY=VALUE secrets, one per line.
  • --secret-mount FILE: File to load as a file-mounted secret.
  • --ignore-empty-secrets: Skip empty values in a secrets file instead of failing.
  • --attribute KEY=VALUE: Attribute to record on the new version. Repeatable. Takes precedence over --attributes.
  • --attributes JSON: JSON object of string attributes, inline or as a file path. Use - to read from stdin.
  • --no-default-attributes: Don't record the git_commit, git_branch, and git_tree attributes the CLI adds in a git repository.

Examples

Deploy to production from the current directory:

lk agent deploy

Deploy to the staging deployment:

lk agent deploy --deployment staging

Promote

Promote the image from a non-production deployment, such as staging, to production without rebuilding.

lk agent promote --deployment NAME [options] [working-dir]

Options for promote:

  • --deployment NAME (alias -d): Non-production deployment to promote. Required.
  • --id ID: Agent ID.

Examples

Promote the staging image to production:

lk agent promote --deployment staging

Rollback

Roll back an agent to a prior version.

lk agent rollback [options] [working-dir]

Options for rollback:

  • --version VERSION: Version to roll back to. Defaults to the previous version.
  • --id ID: Agent ID.

Examples

Roll back to a specific version:

lk agent rollback --id CA_MyAgentId --version 20250809003117

Versions

List an agent's versions, for use with rollback.

lk agent versions [options] [working-dir]

Options for versions:

  • --id ID: Agent ID.
  • --attribute KEY=VALUE, --attributes JSON: Show only versions that have all of these attributes.
  • --json, -j: Print as JSON.

Examples 

lk agent versions --id CA_MyAgentId

Example output. Draining marks a version still finishing sessions after a new deploy:

Using default project [my-project]
Using agent [CA_MyAgentId]
┌────────────────┬────────────┬──────────┬────────┬──────────┬──────────────────────────────────────────────┬──────────────────────┬──────────────────────┐
│ Version        │ Production │ Draining │ Active │ Status   │ Attributes                                   │ Created At           │ Deployed At          │
├────────────────┼────────────┼──────────┼────────┼──────────┼──────────────────────────────────────────────┼──────────────────────┼──────────────────────┤
│ 20250809010422 │ ✓          │ --       │ ✓      │ Deployed │ {"git_branch":"main","git_commit":"4f2a9c1"} │ 2025-08-09T01:00:00Z │ 2025-08-09T01:04:51Z │
│ 20250809003117 │ --         │ ✓        │ ✓      │ Deployed │ --                                           │ 2025-08-09T00:30:00Z │ 2025-08-09T00:31:48Z │
└────────────────┴────────────┴──────────┴────────┴──────────┴──────────────────────────────────────────────┴──────────────────────┴──────────────────────┘

Delete

Delete an agent or one of its deployments. Also available as destroy.

lk agent delete [options] [working-dir]
# or
lk agent destroy [options] [working-dir]

Options for delete:

  • --deployment NAME (alias -d): Non-production deployment to delete. If unset, deletes the entire agent.
  • --id ID: Agent ID.
Caution

Omitting --deployment deletes the whole agent, including production.

Examples

Delete the entire agent:

lk agent delete --id CA_MyAgentId

Delete only the staging deployment:

lk agent delete --deployment staging

Config

Generate a livekit.toml in the working directory for an existing agent.

lk agent config --id AGENT_ID [options] [working-dir]

Options for config:

  • --id AGENT_ID: Agent ID. Required.

Generate Dockerfile

Generate a Dockerfile and .dockerignore in the working directory.

lk agent dockerfile [options] [working-dir]

Options for dockerfile:

  • --overwrite: Overwrite existing files. Default: false.

Examples 

lk agent dockerfile