feat(agents): support uv python project detection and auto setup

Author: rektdeckard

cmd/lk/agent.go

@@ -1005,6 +1005,10 @@ func requireSecrets(_ context.Context, cmd *cli.Command, required, lazy bool) ([
 	secrets := make(map[string]*lkproto.AgentSecret)
 	for _, secret := range cmd.StringSlice("secrets") {
 		secret := strings.Split(secret, "=")
+		if len(secret) != 2 || secret[0] == "" || secret[1] == "" {
+			// Don't include empty secrets
+			continue
+		}
 		agentSecret := &lkproto.AgentSecret{
 			Name:  secret[0],
 			Value: []byte(secret[1]),

pkg/agentfs/docker.go

@@ -21,9 +21,11 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"slices"
 	"strings"
 
 	"github.com/charmbracelet/huh"
+	"github.com/pkg/errors"
 
 	"github.com/livekit/livekit-cli/v2/pkg/util"
 	"github.com/livekit/protocol/logger"
@@ -51,29 +53,25 @@ func CreateDockerfile(dir string, settingsMap map[string]string) error {
 		return fmt.Errorf("unable to fetch client settings from server, please try again later")
 	}
 
-	projectType := ""
-	if isNode(dir) {
-		projectType = "node"
-	} else if isPython(dir) {
-		projectType = "python"
-	} else {
-		return fmt.Errorf("unable to determine project type, please create a Dockerfile in the current directory")
+	projectType, err := DetectProjectType(dir)
+	if err != nil {
+		return errors.Wrap(err, "unable to determine project type, please create a Dockerfile in the current directory")
 	}
 
 	var dockerfileContent []byte
 	var dockerIgnoreContent []byte
-	var err error
 
-	dockerfileContent, err = fs.ReadFile("examples/" + projectType + ".Dockerfile")
+	dockerfileContent, err = fs.ReadFile("examples/" + string(projectType) + ".Dockerfile")
 	if err != nil {
 		return err
 	}
-	dockerIgnoreContent, err = fs.ReadFile("examples/" + projectType + ".dockerignore")
+	dockerIgnoreContent, err = fs.ReadFile("examples/" + string(projectType) + ".dockerignore")
 	if err != nil {
 		return err
 	}
 
-	if projectType == "python" {
+	// TODO: (@rektdeckard) support Node entrypoint validation
+	if projectType.IsPython() {
 		dockerfileContent, err = validateEntrypoint(dir, dockerfileContent, projectType, settingsMap)
 		if err != nil {
 			return err
@@ -93,52 +91,39 @@ func CreateDockerfile(dir string, settingsMap map[string]string) error {
 	return nil
 }
 
-func validateEntrypoint(dir string, dockerfileContent []byte, projectType string, settingsMap map[string]string) ([]byte, error) {
-	fileList := make(map[string]bool)
-	entries, err := os.ReadDir(dir)
-	if err != nil {
-		return nil, err
-	}
-
-	for _, entry := range entries {
-		if entry.IsDir() {
-			continue
-		}
-		fileList[entry.Name()] = true
-	}
-
+func validateEntrypoint(dir string, dockerfileContent []byte, projectType ProjectType, settingsMap map[string]string) ([]byte, error) {
 	valFile := func(fileName string) (string, error) {
-		if _, exists := fileList[fileName]; exists {
-			return fileName, nil
-		}
-
-		var suffix string
-		switch projectType {
-		case "python":
-			suffix = ".py"
-		case "node":
-			suffix = ".js"
+		// NOTE: we need to recurse to find entrypoints which may exist in src/ or some other directory.
+		// This could be a lot of files, so we omit any files in .dockerignore, since they cannot be
+		// used as entrypoints.
+		var fileList []string
+		if err := filepath.WalkDir(dir, func(path string, d os.DirEntry, err error) error {
+			if err != nil {
+				return err
+			}
+			if !d.IsDir() && strings.HasSuffix(d.Name(), ".py") {
+				fileList = append(fileList, path)
+			}
+			return nil
+		}); err != nil {
+			panic(err)
 		}
 
-		// Collect all matching files
-		var options []string
-		for _, entry := range entries {
-			if strings.HasSuffix(entry.Name(), suffix) {
-				options = append(options, entry.Name())
-			}
+		if slices.Contains(fileList, fileName) {
+			return fileName, nil
 		}
 
 		// If no matching files found, return early
-		if len(options) == 0 {
+		if len(fileList) == 0 {
 			return "", nil
 		}
 
 		var selected string
 		form := huh.NewForm(
 			huh.NewGroup(
 				huh.NewSelect[string]().
-					Title(fmt.Sprintf("Select %s file to use as entrypoint", projectType)).
-					Options(huh.NewOptions(options...)...).
+					Title(fmt.Sprintf("Select %s file to use as entrypoint", projectType.Lang())).
+					Options(huh.NewOptions(fileList...)...).
 					Value(&selected).
 					WithTheme(util.Theme),
 			),
@@ -152,8 +137,7 @@ func validateEntrypoint(dir string, dockerfileContent []byte, projectType string
 		return selected, nil
 	}
 
-	err = validateSettingsMap(settingsMap, []string{"python_entrypoint"})
-	if err != nil {
+	if err := validateSettingsMap(settingsMap, []string{"python_entrypoint"}); err != nil {
 		return nil, err
 	}
 
@@ -165,7 +149,7 @@ func validateEntrypoint(dir string, dockerfileContent []byte, projectType string
 
 	lines := bytes.Split(dockerfileContent, []byte("\n"))
 	var result bytes.Buffer
-	for i := 0; i < len(lines); i++ {
+	for i := range lines {
 		line := lines[i]
 		trimmedLine := bytes.TrimSpace(line)
 
@@ -226,7 +210,7 @@ func validateEntrypoint(dir string, dockerfileContent []byte, projectType string
 					return nil, err
 				}
 				for i, arg := range cmdArray {
-					if strings.HasSuffix(arg, ".py") {
+					if strings.HasSuffix(arg, projectType.FileExt()) {
 						cmdArray[i] = newEntrypoint
 						break
 					}
@@ -237,7 +221,7 @@ func validateEntrypoint(dir string, dockerfileContent []byte, projectType string
 				}
 				fmt.Fprintf(&result, "CMD %s\n", newJSON)
 			}
-		} else if bytes.HasPrefix(trimmedLine, []byte(fmt.Sprintf("RUN python %s", pythonEntrypoint))) {
+		} else if bytes.HasPrefix(trimmedLine, fmt.Appendf(nil, "RUN python %s", pythonEntrypoint)) {
 			line = bytes.ReplaceAll(line, []byte(pythonEntrypoint), []byte(newEntrypoint))
 			result.Write(line)
 			if i < len(lines)-1 {

pkg/agentfs/examples/python.Dockerfile …g/agentfs/examples/python.pip.Dockerfilepkg/agentfs/examples/python.Dockerfile renamed to pkg/agentfs/examples/python.pip.Dockerfile pkg/agentfs/examples/python.Dockerfile renamed to pkg/agentfs/examples/python.pip.Dockerfile

@@ -0,0 +1,73 @@
+# This sample Dockerfile creates a production-ready container for a LiveKit voice AI agent
+# syntax=docker/dockerfile:1
+
+# Use the official UV Python base image with Python 3.11 on Debian Bookworm
+# UV is a fast Python package manager that provides better performance than pip
+# We use the slim variant to keep the image size smaller while still having essential tools
+FROM ghcr.io/astral-sh/uv:python3.11-bookworm-slim
+
+# Keeps Python from buffering stdout and stderr to avoid situations where
+# the application crashes without emitting any logs due to buffering.
+ENV PYTHONUNBUFFERED=1
+
+# Create a non-privileged user that the app will run under.
+# See https://docs.docker.com/develop/develop-images/dockerfile_best-practices/#user
+ARG UID=10001
+RUN adduser \
+    --disabled-password \
+    --gecos "" \
+    --home "/home/appuser" \
+    --shell "/sbin/nologin" \
+    --uid "${UID}" \
+    appuser
+
+# Install build dependencies required for Python packages with native extensions
+# gcc: C compiler needed for building Python packages with C extensions
+# python3-dev: Python development headers needed for compilation
+# We clean up the apt cache after installation to keep the image size down
+RUN apt-get update && \
+    apt-get install -y \
+    gcc \
+    python3-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set the working directory to the user's home directory
+# This is where our application code will live
+WORKDIR /home/appuser
+
+# Copy all application files into the container
+# This includes source code, configuration files, and dependency specifications
+# (Excludes files specified in .dockerignore)
+COPY . .
+
+# Change ownership of all app files to the non-privileged user
+# This ensures the application can read/write files as needed
+RUN chown -R appuser:appuser /home/appuser
+
+# Switch to the non-privileged user for all subsequent operations
+# This improves security by not running as root
+USER appuser
+
+# Create a cache directory for the user
+# This is used by UV and Python for caching packages and bytecode
+RUN mkdir -p /home/appuser/.cache
+
+# Install Python dependencies using UV's lock file
+# --locked ensures we use exact versions from uv.lock for reproducible builds
+# This creates a virtual environment and installs all dependencies
+# 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 ensures the container is ready to run immediately without downloading
+# dependencies at runtime, which improves startup time and reliability
+RUN uv run src/agent.py download-files
+
+# Expose the healthcheck port
+# This allows Docker and orchestration systems to check if the container is healthy
+EXPOSE 8081
+
+# Run the application using UV
+# UV will activate the virtual environment and run the agent
+# The "start" command tells the worker to connect to LiveKit and begin waiting for jobs
+CMD ["uv", "run", "src/agent.py", "start"]

pkg/agentfs/examples/python.dockerignore …agentfs/examples/python.pip.dockerignorepkg/agentfs/examples/python.dockerignore renamed to pkg/agentfs/examples/python.pip.dockerignore pkg/agentfs/examples/python.dockerignore renamed to pkg/agentfs/examples/python.pip.dockerignore

@@ -0,0 +1,19 @@
+*.egg-info
+__pycache__
+.pytest_cache
+.ruff_cache
+.env
+.env.*
+.DS_Store
+.idea
+.venv
+.vscode
+*.pyc
+*.pyo
+*.pyd
+.git
+.gitignore
+README.md
+LICENSE
+.github 
+tests/

pkg/agentfs/examples/python.uv.Dockerfile

@@ -15,6 +15,7 @@
 package agentfs
 
 import (
+	"errors"
 	"fmt"
 	"os"
 	"path/filepath"
@@ -23,18 +24,67 @@ import (
 	"k8s.io/apimachinery/pkg/api/resource"
 )
 
-func isPython(dir string) bool {
-	if _, err := os.Stat(filepath.Join(dir, "requirements.txt")); err == nil {
-		return true
+type ProjectType string
+
+const (
+	ProjectTypePythonPip ProjectType = "python.pip"
+	ProjectTypePythonUV  ProjectType = "python.uv"
+	ProjectTypeNode      ProjectType = "node"
+	ProjectTypeUnknown   ProjectType = "unknown"
+)
+
+func (p ProjectType) IsPython() bool {
+	return p == ProjectTypePythonPip || p == ProjectTypePythonUV
+}
+
+func (p ProjectType) Lang() string {
+	switch p {
+	case ProjectTypePythonPip, ProjectTypePythonUV:
+		return "Python"
+	case ProjectTypeNode:
+		return "Node.js"
+	default:
+		return ""
+	}
+}
+
+func (p ProjectType) FileExt() string {
+	switch p {
+	case ProjectTypePythonPip, ProjectTypePythonUV:
+		return ".py"
+	case ProjectTypeNode:
+		return ".js"
+	default:
+		return ""
 	}
-	return false
+}
+
+func isPythonPip(dir string) bool {
+	_, err := os.Stat(filepath.Join(dir, "requirements.txt"))
+	return err == nil
+}
+
+func isPythonUV(dir string) bool {
+	_, err := os.Stat(filepath.Join(dir, "pyproject.toml"))
+	return err == nil
 }
 
 func isNode(dir string) bool {
-	if _, err := os.Stat(filepath.Join(dir, "package.json")); err == nil {
-		return true
+	_, err := os.Stat(filepath.Join(dir, "package.json"))
+	return err == nil
+}
+
+func DetectProjectType(dir string) (ProjectType, error) {
+	if isNode(dir) {
+		return ProjectTypeNode, nil
+	}
+	if isPythonPip(dir) {
+		return ProjectTypePythonPip, nil
+	}
+	if isPythonUV(dir) {
+		return ProjectTypePythonUV, nil
 	}
-	return false
+	return ProjectTypeUnknown, errors.New("project type could not me identified, expect requirements.txt, pyproject.toml, or package.json")
 }
 
 func ParseCpu(cpu string) (string, error) {