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 deploy and logs commands accept --deployment NAME (alias -d) to target a non-production deployment. Omit it to target production. The promote command requires --deployment to name the deployment whose image it promotes. The delete command deletes only the named deployment, or the entire agent if you omit --deployment. Invalid names are rejected rather than falling back to production. The create command always deploys to production, and deploy ignores --deployment when you pass --image or --image-tar.

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

Create

Create a new agent from the working directory and save its ID to livekit.toml. The CLI creates a Dockerfile if there isn't one.

lk agent create [options] [working-dir]

Options for create:

  • --secrets KEY=VALUE: One or more KEY=VALUE secrets. Repeat the flag for each secret. Injected as environment variables into the agent. Takes precedence over --secrets-file.
  • --secrets-file FILE: FILE containing secret KEY=VALUE pairs, one per line. Injected as environment variables into the agent.
  • --secret-mount FILE: Path to a FILE to load as a file-mounted secret in the agent container.
  • --ignore-empty-secrets: If set, will skip environment variables with empty values from secrets files instead of failing.
  • --region REGION: REGION code to deploy the agent to. If unset, the CLI prompts you to select a region. Required in non-interactive mode.
  • --image IMAGE: Pre-built IMAGE from the local Docker daemon (e.g. myimage:latest). Requires Docker. lk agent deploy ignores --deployment with this flag.
  • --image-tar FILE: Pre-built image from an OCI tar FILE (e.g. ./image.tar). No Docker daemon required. lk agent deploy ignores --deployment with this flag.
  • --attribute KEY=VALUE: KEY=VALUE attribute to record on the new version. Repeatable. Merged with --attributes, taking precedence on conflicting keys.
  • --attributes JSON: JSON literal or file path containing an object of string key-value pairs. Use "-" to read from stdin.
  • --no-default-attributes: Don't record the default git_commit, git_branch, and git_tree attributes, which are added when the working directory is a git repository.

See Region codes for --region values and File-mounted secrets for --secret-mount. To write the config to a file other than livekit.toml, pass the global --config FILE option; lk --help lists all global options.

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 Dockerfile unless you pass --image or --image-tar.

lk agent deploy [options] [working-dir]

Options for deploy:

  • --id ID: Agent ID. If unset, uses the ID in livekit.toml; without that file, the CLI prompts you to choose an agent.
  • --attributes JSON: JSON literal or file path containing an object of string key-value pairs. Use "-" to read from stdin.
  • --attribute KEY=VALUE: KEY=VALUE attribute to record on the new version. Repeatable. Merged with --attributes, taking precedence on conflicting keys.
  • --no-default-attributes: Don't record the default git_commit, git_branch, and git_tree attributes, which are added when the working directory is a git repository.
  • --secrets KEY=VALUE: One or more KEY=VALUE secrets. Repeat the flag for each secret. Injected as environment variables into the agent. Takes precedence over --secrets-file.
  • --secrets-file FILE: FILE containing secret KEY=VALUE pairs, one per line. Injected as environment variables into the agent.
  • --secret-mount FILE: Path to a FILE to load as a file-mounted secret in the agent container.
  • --deployment NAME (alias -d): NAME of the deployment. Defaults to production.
  • --ignore-empty-secrets: If set, will skip environment variables with empty values from secrets files instead of failing.
  • --image IMAGE: Pre-built IMAGE from the local Docker daemon (e.g. myimage:latest). Requires Docker. lk agent deploy ignores --deployment with this flag.
  • --image-tar FILE: Pre-built image from an OCI tar FILE (e.g. ./image.tar). No Docker daemon required. lk agent deploy ignores --deployment with this flag.

See Deployments for --deployment and File-mounted secrets for --secret-mount.

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 [options] [working-dir]

Options for promote:

  • --id ID: Agent ID. If unset, uses the ID in livekit.toml; without that file, the CLI prompts you to choose an agent.
  • --deployment NAME (alias -d): NAME of the non-production deployment whose image is promoted to production. Required.

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, as listed by lk agent versions. Required.
  • --id ID: Agent ID. If unset, uses the ID in livekit.toml; without that file, the CLI prompts you to choose an agent.

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. If unset, uses the ID in livekit.toml; without that file, the CLI prompts you to choose an agent.
  • --attribute KEY=VALUE: Show only versions that have this KEY=VALUE attribute. Repeatable; a version must have all of them.
  • --attributes JSON: Show only versions that have every attribute in this JSON object of string key-value pairs, given as a literal or file path. Use "-" to read from stdin.
  • --json (alias -j): Output 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 non-production deployments.

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

Options for delete/destroy:

  • --id ID: Agent ID. If unset, uses the ID in livekit.toml; without that file, the CLI prompts you to choose an agent.
  • --deployment NAME (alias -d): NAME of the non-production deployment to delete. If unset, deletes the entire agent, including production.
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 [options] [working-dir]

Options for config:

  • --id ID: Agent ID. If unset, uses the ID in livekit.toml; without that file, the CLI prompts you to choose an agent.

Generate Dockerfile

Generate a Dockerfile and .dockerignore in the working directory.

lk agent dockerfile [options] [working-dir]

Options for dockerfile:

  • --overwrite: Overwrite existing Dockerfile and .dockerignore files.

Examples 

lk agent dockerfile