# Operating Livekit Agents

Deploys and operates a LiveKit agent in production: shipping a version to LiveKit Cloud...

- Repository: https://github.com/fcakyon/claude-codex-settings (1195 stars)
- Category: Design
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add fcakyon/claude-codex-settings --skill operating-livekit-agents -g -a claude-code -y`
Codex: `npx skills add fcakyon/claude-codex-settings --skill operating-livekit-agents -g -a codex -y`
Cursor: `npx skills add fcakyon/claude-codex-settings --skill operating-livekit-agents -g -a cursor -y`
Gemini CLI: `npx skills add fcakyon/claude-codex-settings --skill operating-livekit-agents -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add fcakyon/claude-codex-settings`

## Description

Deploys and operates a LiveKit agent in production: shipping a version to LiveKit Cloud and rolling it back, secrets and configuration, the worker process model and prewarming, safe async inside worker processes, provider timeouts and degradation, graceful shutdown, SDK upgrades, and observability. Use when the user says "deploy my agent", "roll back the deployment", "tail the agent logs", "the first call after a restart is slow", "attached to a different loop / event loop is closed", "prewarm the VAD", "shut down without dropping calls", "upgrade livekit-agents safely", "correlate logs by session", or is changing an agent codebase that is already live. Not for designing the agent (building-livekit-agents) or reproducing one bad conversation locally (debugging-livekit-agents).

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Operating LiveKit agents

Everything after the agent works: getting a version onto LiveKit Cloud, keeping it fast and alive
under real load, and changing it without breaking what's already running. The commands live under
`lk agent`; read `lk agent --help` and each subcommand's help rather than trusting this skill for
flags, it deliberately doesn't restate them. `reading-livekit-docs` has the deployment and
observability docs.

## Deploying to LiveKit Cloud

On a self-hosted LiveKit server the `lk agent` deploy commands do not apply. Ship the agent as a
container or process under your own tooling (Docker, Kubernetes, systemd), keep secrets in its
environment, and look up the server side with `lk docs get-page /home/self-hosting`. The worker,
shutdown, and observability guidance below applies either way.

The shape is stable even as the flags move:

1. **A project directory is bound to an agent** by a config file the CLI writes (`livekit.toml`).
   Commands run from that directory find the agent without an id.
2. **The agent ships as a container.** The CLI can generate a Dockerfile for the project, or you
   bring a prebuilt image. Run the container's start command locally (`lk agent start`) before the
   first deploy, it's production mode, with production logging and a shutdown drain, and it is
   not what `dev` mode runs.
3. **Each deploy creates a version** and rolls it out. `status`, `versions`, and `logs` (build logs
   and deploy logs are separate) tell you what's live and why a rollout failed.
4. **Secrets are injected as environment variables** and managed apart from the code, never
   baked into the image or committed. Changing secrets restarts the agent.
5. **Rollback returns to a previous version.** How instant that is depends on the plan; the docs
   say. Know the rollback command before you need it.

The rest: https://github.com/fcakyon/claude-codex-settings/blob/HEAD/plugins/livekit-skills/skills/operating-livekit-agents/SKILL.md