# VSS code_executor Docker Backend Implementation for Sandboxed Execution

> Implement secure VSS code_executor Docker backend for sandboxed Python code execution. Discover strict security policies, non-root containers, and resource limits for isolated tasks in the Video Search & Summarization platform.

- Repository: [NVIDIA AI Blueprints/video-search-and-summarization](https://github.com/NVIDIA-AI-Blueprints/video-search-and-summarization)
- Tags: how-to-guide
- Published: 2026-05-15

---

**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`](https://github.com/NVIDIA-AI-Blueprints/video-search-and-summarization/blob/main/agent/src/vss_agents/tools/code_executor/python_executor.py#L35-L53) 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`](https://github.com/NVIDIA-AI-Blueprints/video-search-and-summarization/blob/main/agent/src/vss_agents/tools/code_executor/docker_backend/docker_executor.py#L30-L158) 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`](https://github.com/NVIDIA-AI-Blueprints/video-search-and-summarization/blob/main/agent/src/vss_agents/tools/code_executor/docker_backend/image_builder.py#L50-L63) 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:

```python
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`](https://github.com/NVIDIA-AI-Blueprints/video-search-and-summarization/blob/main/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`](https://github.com/NVIDIA-AI-Blueprints/video-search-and-summarization/blob/main/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`](https://github.com/NVIDIA-AI-Blueprints/video-search-and-summarization/blob/main/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`](https://github.com/NVIDIA-AI-Blueprints/video-search-and-summarization/blob/main/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`](https://github.com/NVIDIA-AI-Blueprints/video-search-and-summarization/blob/main/main.py) serving as the entrypoint command inside the isolated environment.