Agent crashes when deployed to LiveKit Cloud

[mattvick]

Summary

Deployed Node agent enters CrashLoop in LiveKit Cloud because required turn-detector model files are not found at runtime, even though download-files is run during Docker build.

Environment

• Template: agent-starter-node
• Runtime: LiveKit Cloud deployment
• Status observed: CrashLoop

Steps to reproduce

Build and deploy the agent using the current Dockerfile.

git clone https://github.com/livekit-examples/agent-starter-node.git
cd agent-starter-node
pnpm i
lk cloud auth
lk agent create

1. Select project
2. Select region for agent deployment
3. Select Yes when prompted Would you like to view logs?
4. Observe logs

Actual behavior

Agent fails during startup with missing turn-detector artifacts and times out:

• File not found in cache: livekit/turn-detector/onnx/model_q8.onnx
• agents-plugins-livekit failed to initialize ... Required model files not found locally
• runner initialization timed out

Expected behavior

Agent should start successfully, with required model files available to the runtime user.

Root cause

Model files are downloaded during build under root’s cache directory (e.g. /root/.cache/...), but runtime process executes as appuser and reads cache from that user’s home (e.g. /app/.cache/...).
This user/home mismatch makes the downloaded files invisible at runtime.

Impact

• Deployment fails to become healthy.
• Agent remains in CrashLoop.
• Cloud dashboard metadata can be incomplete/unreliable while startup fails (e.g. blank Agent Name).

Workaround / Fix

Resolved by #29

Download model files as the same user that runs the agent process in production:

• Remove build-stage pnpm download-files.
• Run node dist/main.js download-files after USER appuser in production stage.

Acceptance criteria

• Agent starts without missing model file errors.
• Deployment reaches healthy/running state.
• No runner initialization timed out caused by missing turn-detector cache files.