Docker configuration

Every deployment path -- Cloud, self-hosted, or hybrid -- starts with a Docker image. A well-structured Dockerfile means faster builds, smaller images, and fewer surprises in production. This chapter walks through multi-stage builds for both Python and Node.js voice agents, with optimization techniques that cut image size and build time dramatically.

What you'll learn

• How to write multi-stage Dockerfiles for Python and Node.js agents
• Layer caching strategies that make rebuilds fast
• Image size optimization techniques (minimal base images, dependency pruning)
• Production-ready patterns for LiveKit agent containers

Why Docker matters for voice agents

Voice agents have a specific constraint that most web apps do not: they process real-time audio. A container that takes 60 seconds to start means 60 seconds of dead air for the first caller after a scale-up event. A bloated image means slower pulls across your cluster. Every megabyte and every second counts.

Python agent Dockerfile

Here is a production-ready multi-stage Dockerfile for a Python voice agent:

# Stage 1: Install dependencies
FROM python:3.12-slim AS builder
WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Stage 2: Production image
FROM python:3.12-slim
WORKDIR /app

# Copy installed packages from builder
COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
COPY --from=builder /usr/local/bin /usr/local/bin

# Copy application code
COPY . .

# Run as non-root user
RUN useradd --create-home agent
USER agent

CMD ["python", "agent.py", "start"]

Node.js agent Dockerfile

For TypeScript/Node.js agents, the pattern is similar but uses npm and a Node.js base image:

# Stage 1: Install dependencies and build
FROM node:22-slim AS builder
WORKDIR /app

COPY package.json package-lock.json ./
RUN npm ci --production=false

COPY tsconfig.json ./
COPY src ./src
RUN npm run build

# Stage 2: Production image
FROM node:22-slim
WORKDIR /app

COPY package.json package-lock.json ./
RUN npm ci --omit=dev

COPY --from=builder /app/dist ./dist

# Run as non-root user
USER node

CMD ["node", "dist/agent.js", "start"]

The .dockerignore file

A .dockerignore file prevents unnecessary files from being sent to the Docker build context. Without it, COPY . . pulls in everything -- git history, node_modules, virtual environments, test data.

.git
.gitignore
.env
.env.*
__pycache__
*.pyc
.pytest_cache
.mypy_cache
node_modules
dist
.venv
venv
*.md
tests/
docs/
.vscode/
.idea/

Layer caching strategies

Docker caches each layer. If a layer's inputs have not changed, Docker reuses the cached version. The key principle: put things that change rarely at the top, things that change often at the bottom.

FROM python:3.12-slim
WORKDIR /app

# This layer is cached until requirements.txt changes
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# This layer rebuilds every time agent code changes
# But the pip install layer above stays cached
COPY . .

CMD ["python", "agent.py", "start"]

Image size comparison

Here is what different base image choices mean for your final image size:

The agent.toml configuration

LiveKit Cloud uses agent.toml to configure deployment behavior:

[agent]
name = "dental-receptionist"
version = "1.0.0"

[build]
dockerfile = "Dockerfile"
context = "."

[scaling]
min_instances = 1
max_instances = 10

This file tells lk agent deploy which Dockerfile to use, what to name the agent, and how to scale it. You will explore the scaling section in depth in the auto-scaling chapter.

Testing your Docker image locally

Always test the image locally before deploying:

# Build the image
docker build -t my-agent .

# Check image size
docker images my-agent

# Run locally to verify startup
docker run --rm \
-e LIVEKIT_URL=wss://your-project.livekit.cloud \
-e LIVEKIT_API_KEY=APIxxxxxxx \
-e LIVEKIT_API_SECRET=xxxxxxxxxxxxxxx \
-e OPENAI_API_KEY=sk-xxx \
-e DEEPGRAM_API_KEY=xxx \
my-agent

What you learned

• Multi-stage builds separate dependency installation from the final image, keeping production containers lean
• Layer ordering matters: dependencies before application code ensures fast rebuilds
• .dockerignore prevents bloat from git history, virtual environments, and test data entering the build context
• python:3.12-slim and node:22-slim are the recommended base images for voice agents
• Always test your Docker image locally before deploying to any environment

Next up

Your agent is containerized. In the next chapter, you will deploy it to LiveKit Cloud using the lk CLI, configure secrets, and set up rollback procedures.