Thanks — I understand you’re running

download-files

during your Docker build and it fails because your code reads runtime environment variables that aren’t set at build time. I’ll walk you through the cause and a safe fix so

download-files

can run during image build without needing runtime secrets. Acknowledging the issue • You’re seeing errors during the build step that runs

download-files

because some code is trying to read environment variables (like

LIVEKIT_API_KEY

,

LIVEKIT_API_SECRET

,

LIVEKIT_URL

) at import/module load time. • The

download-files

command itself only downloads model files and does not need LiveKit credentials. What’s causing the failure • Your agent code (for example in

agent.py

) likely accesses

os.getenv()

or calls

load_dotenv()

at the top level or during module import. That runs during the build step and fails because those env vars aren’t defined there. • Any initialization logic that uses runtime-only environment values must be deferred until the actual runtime entrypoint. How to fix it (recommended) 1. Move all environment-variable access into the runtime-entrypoint or functions that run only at runtime. ◦ Do not call

os.getenv()

or

load_dotenv()

at module scope. ◦ Call them inside your

entrypoint

/

main()

async function or wherever you establish a LiveKit connection. Example pattern (conceptual):

# agent.py (top-level imports only)
from livekit.agents import AgentSession
from livekit.plugins import silero
from livekit.plugins.turn_detector.multilingual import MultilingualModel

# no os.getenv or load_dotenv here

async def entrypoint(ctx):
    import os
    livekit_url = os.getenv("LIVEKIT_URL")    # safe here
    api_key = os.getenv("LIVEKIT_API_KEY")
    api_secret = os.getenv("LIVEKIT_API_SECRET")

    session = AgentSession(
        vad=silero.VAD.load(),
        turn_detection=MultilingualModel(),
        # other runtime config
    )
    await session.start(...)

1. If you use

load_dotenv()

, call it inside the runtime entrypoint (not at import time). 2. Keep model/plugin initialization that is safe for build-time (e.g., loading plugin classes or calling their

load()

methods if they only fetch local model files) at module level only if those actions don’t require runtime secrets. Otherwise defer them too. Dockerfile notes (example) • Install dependencies first, copy sources, then run `download-files`: 1. COPY dependency manifest and install deps 2. COPY source code 3. RUN your agent CLI command to download files Example sequence:

COPY pyproject.toml .
RUN uv sync --locked

COPY src/ src/
RUN uv run src/agent.py download-files

This will succeed provided your modules no longer access runtime env vars at import time. Extra tips • Use

.dockerignore

to keep secrets like

.env

out of the image. • If you must have conditional code paths (build vs runtime), you can detect when running

download-files

by checking sys.argv in the entry module and avoid importing runtime-only code during that command. If you’d like, share a short snippet of your

agent.py

(the top-level imports and any top-level

os.getenv()

or

load_dotenv()

calls). I can point out the exact lines to move so

download-files

will run cleanly during build. Sources: Silero VAD plugin | LiveKit Documentation | Server startup modes | LiveKit Documentation | Build a healthcare intake assistant with an Anam avatar | LiveKit