Cache download-files in Dockerfile templates by using standalone commands (#848)

Author: aryeila

pkg/agentfs/examples/node.Dockerfile

@@ -35,6 +35,12 @@ COPY package.json pnpm-lock.yaml ./
 # --frozen-lockfile ensures we use exact versions from pnpm-lock.yaml for reproducible builds
 RUN pnpm install --frozen-lockfile
 
+# Pre-download any ML models or files the agent needs
+# This runs before COPY . . so the download layer is cached across code-only changes.
+# The standalone CLI discovers installed @livekit/agents-plugin-* packages without
+# loading your agent code.
+RUN npx livekit-agents download-files
+
 # Copy all remaining application files into the container
 # This includes source code, configuration files, and dependency specifications
 # (Excludes files specified in .dockerignore)
@@ -44,12 +50,6 @@ COPY . .
 # Your package.json must contain a "build" script, such as `"build": "tsc"`
 RUN pnpm build
 
-# Pre-download any ML models or files the agent needs
-# This ensures the container is ready to run immediately without downloading
-# dependencies at runtime, which improves startup time and reliability
-# Your package.json must contain a "download-files" script, such as `"download-files": "pnpm run build && node dist/agent.js download-files"`
-RUN pnpm download-files
-
 # Remove dev dependencies for a leaner production image
 RUN pnpm prune --prod
 

pkg/agentfs/examples/python.pip.Dockerfile

@@ -42,16 +42,17 @@ RUN python -m venv .venv
 ENV PATH="/app/.venv/bin:$PATH"
 RUN pip install --no-cache-dir -r requirements.txt
 
+# Pre-download any ML models or files the agent needs
+# This runs before COPY . . so the download layer is cached across code-only changes.
+# The module-level command discovers installed livekit-plugins-* packages without
+# loading your agent code.
+RUN python -m livekit.agents download-files
+
 # Copy all remaining application files into the container
 # This includes source code, configuration files, and dependency specifications
 # (Excludes files specified in .dockerignore)
 COPY . .
 
-# Pre-download any ML models or files the agent needs
-# This ensures the container is ready to run immediately without downloading
-# dependencies at runtime, which improves startup time and reliability
-RUN python "{{.ProgramMain}}" download-files
-
 # --- Production stage ---
 # Build tools (gcc, g++, python3-dev) are not included in the final image
 FROM base

pkg/agentfs/examples/python.uv.Dockerfile

@@ -46,16 +46,17 @@ RUN mkdir -p src
 # Ensure your uv.lock file is checked in for consistency across environments
 RUN uv sync --locked
 
+# Pre-download any ML models or files the agent needs
+# This runs before COPY . . so the download layer is cached across code-only changes.
+# The module-level command discovers installed livekit-plugins-* packages without
+# loading your agent code.
+RUN uv run --module livekit.agents download-files
+
 # Copy all remaining application files into the container
 # This includes source code, configuration files, and dependency specifications
 # (Excludes files specified in .dockerignore)
 COPY . .
 
-# Pre-download any ML models or files the agent needs
-# This ensures the container is ready to run immediately without downloading
-# dependencies at runtime, which improves startup time and reliability
-RUN uv run "{{.ProgramMain}}" download-files
-
 # --- Production stage ---
 # Build tools (gcc, g++, python3-dev) are not included in the final image
 FROM base