VSS code_executor Docker Backend Implementation for Sandboxed Execution

The VSS code_executor leverages a Docker backend with strict security policies, non-root containers, and resource limits to provide isolated, sandboxed execution of arbitrary Python code within the Video Search & Summarization platform.

The NVIDIA-AI-Blueprints/video-search-and-summarization repository implements a robust VSS code_executor Docker backend implementation for sandboxed execution that enables AI agents to safely run untrusted Python code. This system combines a declarative configuration layer with a hardened container runtime to prevent privilege escalation and resource abuse. All execution occurs inside ephemeral Docker containers managed through the Nat framework, ensuring that code analysis and dynamic tool generation remain strictly isolated from the host system.

Architecture Overview

The Docker backend consists of four coordinated components that handle image building, container lifecycle, and secure execution:

• CodeExecutorConfig – A Pydantic model defined in agent/src/vss_agents/tools/code_executor/python_executor.py that specifies the backend type, GPU requirements, base image, and language packages.
• DockerExecutor – The core sandbox engine in agent/src/vss_agents/tools/code_executor/docker_backend/docker_executor.py that manages container creation, file packaging, and security constraints.
• ImageBuilder – A singleton class in agent/src/vss_agents/tools/code_executor/docker_backend/image_builder.py that constructs and caches custom Docker images based on requested dependencies.
• python_executor – The public entry point function (L75-L115) that registers the tool with the Nat framework and orchestrates the build-and-run sequence.

This layered architecture separates configuration from execution, allowing the VSS agent to dynamically spawn isolated environments without manual container management.

Security and Isolation Mechanisms

The VSS code_executor Docker backend implementation for sandboxed execution enforces defense-in-depth through multiple kernel and Docker-level restrictions implemented in DockerExecutor.run_code():

• Non-root execution – Containers run as user="1000:1000" to prevent host privilege escalation.
• Capability drop – All Linux capabilities are removed via cap_drop=["ALL"].
• No new privileges – The security_opt=["no-new-privileges:true"] flag prevents setuid binaries from gaining additional permissions.
• Resource quotas – Configurable limits include CPU (nano_cpus), memory (mem_limit), and process count (pids_limit).
• Network isolation – The default configuration disables network access unless explicitly enabled (network_disabled=not network).
• GPU passthrough – Optional device requests allow sandboxed access to NVIDIA GPUs when gpu=True is specified in the configuration.

These defaults ensure that malicious or buggy code cannot escape the container, exhaust host resources, or access sensitive network services.

Execution Flow

The sandbox lifecycle follows a four-stage pipeline that transforms a code string into a captured output:

1. Configuration – The agent instantiates CodeExecutorConfig with parameters such as base_image="python:3.11-slim" and language_packages=["numpy","pandas"].

2. Image Construction – DockerExecutor.build_image() invokes ImageBuilder.build_image() (L97-L135) to generate a custom image tagged as deep-search/<name>-executor. The builder dynamically composes a Dockerfile via _generate_dockerfile() (L13-L73) and caches the result to avoid redundant builds.

3. Container Execution – DockerExecutor.run_code() (L80-L158) performs the following steps:

   • Packages the supplied files into a tar archive using _pack_files() (L36-L78), marking scripts as executable.
   • Creates a container with the security constraints detailed above.
   • Uploads the tarball and executes the entrypoint command (e.g., python /job-<timestamp>/main.py).
   • Enforces a timeout while streaming stdout and stderr logs.

4. Result Collection – The container is immediately torn down after execution, and the tool returns a CodeExecutorOutput containing either the captured stdout or an error payload.

Practical Implementation Example

Below is a complete example demonstrating how to invoke the executor within a VSS agent workflow:

from vss_agents.tools.code_executor.python_executor import CodeExecutorConfig, python_executor
from nat.builder.builder import Builder
import asyncio

# Configure the sandbox environment

config = CodeExecutorConfig(
    backend="docker",
    gpu=False,
    base_image="python:3.11-slim",
    language_packages=["numpy", "pandas"],
)

# Initialize the Nat builder (provided by VSS runtime)

builder = Builder()

# Obtain the async tool generator

exec_gen = python_executor(config, builder)

# Extract the execution coroutine

function_info = await exec_gen.__anext__()
run_fn = function_info.single_fn

# Define code to run inside the sandbox

code = """
import numpy as np
import pandas as pd
df = pd.DataFrame({'x': np.arange(5), 'y': np.arange(5) ** 2})
print(df.to_json())
"""
files = {}  # Additional files can be provided here

# Execute and retrieve results

output = await run_fn({"code": code, "files": files})
print("Sandbox output:", output.message)

Under the hood, python_executor builds the image if absent, while DockerExecutor handles the transient container lifecycle and log capture.

Summary

• The VSS code_executor relies on a Docker backend to provide hardware-isolated, sandboxed execution for arbitrary Python code.
• Security hardening includes non-root users, dropped capabilities, no-new-privileges flags, and disabled networking by default.
• The ImageBuilder singleton caches custom environments to optimize build times across multiple executions.
• Execution occurs through DockerExecutor.run_code() in agent/src/vss_agents/tools/code_executor/docker_backend/docker_executor.py, which manages file packaging, container lifecycle, and resource enforcement.
• The system integrates with the Nat framework via python_executor() in agent/src/vss_agents/tools/code_executor/python_executor.py, enabling LangChain-compatible tool invocation.

Frequently Asked Questions

How does the VSS code_executor prevent privilege escalation inside containers?

The implementation enforces multiple Linux security mechanisms: containers run as non-root (user="1000:1000"), drop all capabilities (cap_drop=["ALL"]), and set no-new-privileges:true to block setuid attacks. These settings are applied in DockerExecutor.run_code() within agent/src/vss_agents/tools/code_executor/docker_backend/docker_executor.py.

What role does ImageBuilder play in the Docker backend?

ImageBuilder is a singleton class that constructs and caches Docker images based on the base_image and language_packages specified in CodeExecutorConfig. It generates Dockerfiles dynamically via _generate_dockerfile() and tags images as deep-search/<name>-executor, ensuring that identical environments are reused across process lifetimes while cleaning up via atexit handlers.

Can the sandbox access GPU resources for accelerated computing?

Yes. Setting gpu=True in CodeExecutorConfig instructs DockerExecutor to include NVIDIA device requests in the container creation call. This allows sandboxed code to leverage CUDA while maintaining all other security constraints, though network access remains disabled unless explicitly enabled.

How are user files transferred into the execution container?

Files are packaged into a tar archive by _pack_files() (L36-L78) in docker_executor.py, which creates directory structures and sets executable permissions on scripts. The archive is uploaded to the container filesystem before execution, with main.py serving as the entrypoint command inside the isolated environment.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}