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 AGENT_ID: Agent ID.

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 [--id IDs]: Filter by agent ID. Repeatable.
  • --project PROJECT_NAME: Project to list. Defaults to the project in livekit.toml, or the default project.

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. Also available as tail.

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

Options for logs:

  • --deployment NAME (alias -d): Deployment to stream logs from. Defaults to production.
  • --id ID: Agent ID.
  • --log-type TYPE: deploy or build. Default: deploy.

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 AGENT_ID: Agent ID.

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

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 AGENT_ID: Agent ID.

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: 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.
  • --id ID: Agent ID.
  • --overwrite: Overwrite existing secrets. Default: false.

Examples

Update secrets without overwriting existing keys:

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

Overwrite existing keys explicitly:

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