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

Manage deployed agents

Reference for the LiveKit CLI commands that monitor and maintain agents deployed to LiveKit Cloud.

On this page

Overview Status Examples Status valuesList Examples Logs Examples Restart Examples Update Examples Secrets Examples Update secrets Examples

Overview

Use these commands to check on agents deployed to LiveKit Cloud, stream logs, manage secrets, and restart. They resolve the project and agent like the other deployment commands, so commands that take --id default to the agent in livekit.toml. To install the CLI, see Install the CLI.

Status

Show the current status of an agent.

lk agent status [options] [working-dir]

Options for status:

  • --id ID: Agent ID. If unset, uses the ID in livekit.toml; without that file, the CLI prompts you to choose an agent.
  • --json (alias -j): Output as JSON.

Examples 

lk agent status --id CA_MyAgentId

Example output, with one row per deployment:

Using default project [my-project]
Using agent [CA_MyAgentId]
┌──────────────┬─────────────┬────────────────┬─────────┬────────────┬──────────┬────────────┬─────────┬───────────┬──────────────────────┬──────────────────────┐
│ ID           │ Name        │ Version        │ Region  │ Deployment │ Status   │ CPU        │ Mem     │ Replicas  │ Deployed At          │ Last Observed        │
├──────────────┼─────────────┼────────────────┼─────────┼────────────┼──────────┼────────────┼─────────┼───────────┼──────────────────────┼──────────────────────┤
│ CA_MyAgentId │ steve-agent │ 20250809003117 │ us-east │ production │ Running  │ 0m / 2000m │ 0 / 4GB │ 1 / 1 / 1 │ 2025-08-09T00:31:48Z │ 2025-08-09T02:15:07Z │
│ CA_MyAgentId │ steve-agent │ 20250809010422 │ us-east │ staging    │ Sleeping │ 0m / 2000m │ 0 / 4GB │ 0 / 0 / 1 │ 2025-08-09T01:04:51Z │ 2025-08-09T02:15:07Z │
└──────────────┴─────────────┴────────────────┴─────────┴────────────┴──────────┴────────────┴─────────┴───────────┴──────────────────────┴──────────────────────┘

Status values

Normal statuses

Agent statusDescription
Setting UpAgent created; waiting for provisioning.
BuildingBuilding images for a new version.
RunningAgent is running and serving users.
UpdatingAgent is pending update.
SchedulingAgent is being deployed.
DeletingAgent is pending delete.

Sleep

Agents on some plans scale down to zero instances. See cold start.

Agent statusDescription
SleepingAgent has been scaled down.
WakingAgent is scaling back up to serve a new user.

Errors

Agent statusDescription
ErrorAgent program exited with a non-zero error code.
CrashLoopAgent pod is crash looping.
DisabledAutomatically disabled after a long error state. Deploy a new version to resolve.
Build FailedLatest build failed.
Server ErrorLiveKit Cloud infrastructure error. See the Status page .
DeletedAgent has been deleted.
SuspendedProject suspended for suspicious behavior.

List

List all deployed agents in the project.

lk agent list [options]

Options for list:

  • --id IDs: Filter to one or more agent IDs. Repeatable.
  • --json (alias -j): Output as JSON.

The command lists agents in the project from livekit.toml, or the default project. To list another project, pass the global --project PROJECT_NAME option, for example lk --project PROJECT_NAME agent list.

Examples 

lk agent list

Example output:

Using default project [my-project]
┌─────────────────┬───────────────┬─────────┬─────────────────────┬────────────────┬──────────────────────┐
│ ID              │ Dispatch Name │ Regions │ Deployments         │ Version        │ Deployed At          │
├─────────────────┼───────────────┼─────────┼─────────────────────┼────────────────┼──────────────────────┤
│ CA_MyAgentId    │ steve-agent   │ us-east │ production,staging   │ 20250809003117 │ 2025-08-09T00:31:48Z │
└─────────────────┴───────────────┴─────────┴─────────────────────┴────────────────┴──────────────────────┘

Logs

Stream an agent's logs.

lk agent logs [options] [working-dir]
# or
lk agent tail [options] [working-dir]

Options for logs/tail:

  • --id ID: Agent ID. If unset, uses the ID in livekit.toml; without that file, the CLI prompts you to choose an agent.
  • --log-type TYPE: Log TYPE to retrieve. Valid values: deploy, build. Default: deploy.
  • --deployment NAME (alias -d): NAME of the deployment. Defaults to production.

For more on --deployment, see Deployments.

Examples

Tail build logs from production:

lk agent logs --id CA_MyAgentId --log-type build

Tail deploy logs from the staging deployment:

lk agent logs --deployment staging

Restart

Restart an agent's server pool without interrupting active sessions.

lk agent restart [options] [working-dir]

Options for restart:

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

Examples 

lk agent restart --id CA_MyAgentId

Update

Update the secrets of the agent in livekit.toml. Restarts the agent servers without interrupting active sessions. To target an agent by ID, use update-secrets.

lk agent update [options] [working-dir]

Options for update:

  • --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.

For --secret-mount, see File-mounted secrets.

Examples 

lk agent update --secrets OPENAI_API_KEY=sk-new

Secrets

List an agent's secret names, without values.

lk agent secrets [options] [working-dir]

Options for secrets:

  • --id ID: Agent ID. If unset, uses the ID in livekit.toml; without that file, the CLI prompts you to choose an agent.
  • --json (alias -j): Output as JSON.

Examples 

lk agent secrets --id CA_MyAgentId

Example output:

Using default project [my-project]
Using agent [CA_MyAgentId]
┌────────────────┬──────────────────────┬──────────────────────┐
│ Name           │ Created At           │ Updated At           │
├────────────────┼──────────────────────┼──────────────────────┤
│ OPENAI_API_KEY │ 2025-08-08T23:32:29Z │ 2025-08-09T00:31:10Z │
│ GOOGLE_API_KEY │ 2025-08-08T23:32:29Z │ 2025-08-09T00:31:10Z │
│ GROQ_API_KEY   │ 2025-08-08T23:32:29Z │ 2025-08-09T00:31:10Z │
└────────────────┴──────────────────────┴──────────────────────┘

Update secrets

Update an agent's secrets and restart it.

lk agent update-secrets [options] [working-dir]

Options for update-secrets:

  • --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.
  • --id ID: Agent ID. If unset, uses the ID in livekit.toml; without that file, the CLI prompts you to choose an agent.
  • --overwrite: Replace all of the agent's existing secrets with the ones given, instead of adding to and updating them. Asks for confirmation unless --yes.

For --secret-mount, see File-mounted secrets.

Examples

Add or update the secrets in a file, keeping the agent's other secrets:

lk agent update-secrets --id CA_MyAgentId \
  --secrets-file ./secrets.env

Replace all of the agent's secrets with only OPENAI_API_KEY:

lk agent update-secrets --id CA_MyAgentId \
  --secrets OPENAI_API_KEY=sk-xxx \
  --overwrite