Agent Sandboxing Tutorial: Building Secure LLM Applications

Introduction to Agent Sandboxing

As Large Language Models (LLMs) evolve from simple conversational agents to powerful autonomous entities capable of executing code, interacting with external APIs, and making real-world decisions, the need for solid security measures becomes paramount. An LLM agent, when given the ability to act, can become a significant security risk if not properly constrained. This is where agent sandboxing comes into play. Sandboxing an agent means creating an isolated environment where it can operate without affecting the host system or accessing unauthorized resources. This tutorial will explore the practical aspects of agent sandboxing, providing hands-on examples to demonstrate how to build secure and reliable LLM applications.

The core principle behind sandboxing is least privilege: an agent should only have access to the resources absolutely necessary for its function, and no more. Without proper sandboxing, a malicious or errant agent could:

• Execute arbitrary code on the host system, leading to data theft or system compromise.
• Access sensitive files or network resources.
• Initiate unwanted external API calls, incurring costs or performing unauthorized actions.
• Exfiltrate confidential data through various channels.

By implementing effective sandboxing, we can mitigate these risks, allowing us to use the immense power of LLM agents while maintaining control and security.

Understanding the Threats: Why Sandbox?

Before we explore the ‘how,’ let’s solidify the ‘why.’ The threats posed by un-sandboxed agents are multifaceted and can be categorized as follows:

1. Code Execution Vulnerabilities

Many advanced LLM agents are designed to write and execute code (e.g., Python scripts) to solve problems, analyze data, or interact with tools. If this execution isn’t contained, the agent could:

• System Command Injection: Generate code that calls os.system('rm -rf /') or similar destructive commands.
• Remote Code Execution (RCE): Exploit vulnerabilities in libraries to gain control over the host.
• Resource Exhaustion: Create infinite loops or allocate excessive memory/CPU, leading to denial of service.

2. Data Access and Exfiltration

An agent might be tasked with processing sensitive data. Without sandboxing, it could:

• Unauthorized File Access: Read files outside its designated working directory (e.g., /etc/passwd, API keys).
• Network Access: Connect to internal network resources, external malicious servers, or exfiltrate data to arbitrary endpoints.
• Prompt Injection via File Reads: If an agent can read arbitrary files, a malicious actor could craft a prompt that tricks the agent into reading a sensitive file and then incorporating its content into a subsequent output.

3. API and Tool Abuse

Agents often interact with external APIs or custom tools. Unrestricted access can lead to:

• Unauthorized API Calls: Make calls to sensitive APIs it shouldn’t access (e.g., user management, payment processing).
• Cost Overruns: Trigger expensive API calls or resource-intensive cloud functions.
• Malicious Actions: If an agent has access to an email API, it could send spam or phishing emails.

Sandboxing Techniques and Tools

There are several layers and techniques we can employ for agent sandboxing, ranging from simple code review to sophisticated containerization.

1. Language-Level Sandboxing (Code Interpreter Restrictions)

If your agent primarily generates and executes code (e.g., Python), you can restrict the interpreter’s capabilities.

Example: Restricted Python Execution with exec() and Whitelisting

A common scenario is an agent generating Python code. Instead of directly calling exec() or eval() on arbitrary strings, you can restrict the available globals and built-ins.

import subprocess
import os

def safe_execute_python_code(code: str, allowed_modules: list = None, timeout: int = 10):
 if allowed_modules is None:
 allowed_modules = ['math', 'json', 're'] # Whitelist safe modules

 # Create a restricted global namespace
 restricted_globals = {
 '__builtins__': {key: globals()['__builtins__'][key] for key in [
 'print', 'len', 'str', 'int', 'float', 'list', 'dict', 'tuple', 'set', 
 'range', 'sum', 'min', 'max', 'abs', 'round', 'type', 'isinstance', 'enumerate'
 ]},
 '__name__': '__main__'
 }

 # Dynamically import allowed modules into the restricted namespace
 for module_name in allowed_modules:
 try:
 restricted_globals[module_name] = __import__(module_name)
 except ImportError:
 print(f"Warning: Could not import allowed module {module_name}")

 try:
 # Use subprocess to execute in an isolated process for better isolation
 # This is more solid than just `exec` in the current process
 # and allows for timeouts and resource limits.
 process = subprocess.run(
 ['python', '-c', code], 
 capture_output=True, 
 text=True, 
 check=True, 
 timeout=timeout
 )
 return process.stdout
 except subprocess.CalledProcessError as e:
 return f"Error during execution: {e.stderr}"
 except subprocess.TimeoutExpired:
 return "Error: Code execution timed out."
 except Exception as e:
 return f"An unexpected error occurred: {e}"

# Example Usage:
# Safe code
agent_code_safe = "import math; print(math.sqrt(16))"
print(f"Safe code output: {safe_execute_python_code(agent_code_safe)}")

# Malicious code attempt (will be blocked by subprocess isolation and built-in restrictions if direct exec was used)
# With subprocess, the 'os' import would still fail in the child process unless specifically allowed.
agent_code_malicious_os = "import os; print(os.listdir('/'))"
print(f"Malicious OS code output: {safe_execute_python_code(agent_code_malicious_os)}")

# Malicious code attempt (trying to read a file)
agent_code_malicious_file = "with open('/etc/passwd', 'r') as f: print(f.read())"
print(f"Malicious file read code output: {safe_execute_python_code(agent_code_malicious_file)}")

# Code with an infinite loop (will be caught by timeout)
agent_code_loop = "while True: pass"
print(f"Looping code output: {safe_execute_python_code(agent_code_loop, timeout=3)}")

Explanation:

• We define a safe_execute_python_code function.
• It takes the agent’s generated code as input.
• Instead of directly executing in the current process, we use subprocess.run. This is a crucial step for true isolation, as it runs the code in a separate Python interpreter process. This process inherits minimal privileges and is not the same as the parent process running your main application.
• The allowed_modules list acts as a whitelist. Even if the agent tries to import os or sys, it won’t be available in the restricted environment of the subprocess unless explicitly allowed (which it shouldn’t be for general agent code).
• timeout prevents resource exhaustion from infinite loops.
• capture_output=True and text=True allow us to capture the agent’s output.
• check=True raises an exception if the subprocess returns a non-zero exit code (indicating an error).

While this approach significantly improves security over direct exec(), it’s not foolproof. A highly sophisticated agent might still find ways to exploit underlying system calls if the Python environment itself is vulnerable or if too many modules are whitelisted.

2. Operating System Level Sandboxing (Containers & Virtual Machines)

For the most solid sandboxing, especially when agents might generate code in multiple languages or interact with the filesystem/network, OS-level isolation is indispensable.

a. Docker Containers

Docker is an excellent choice for sandboxing. Each agent execution can occur within its own, short-lived container with strictly defined resource limits and network access policies.

Practical Example: Docker for Agent Execution

Step 1: Create a Dockerfile for the agent’s execution environment.

# Dockerfile
FROM python:3.9-slim-buster

WORKDIR /app

# Create a non-root user for security
RUN useradd --no-create-home --shell /bin/bash agentuser
USER agentuser

# Copy a simple script that the agent might generate and we want to execute
COPY run_agent_code.py .

ENTRYPOINT ["python", "run_agent_code.py"]

Step 2: Create run_agent_code.py. This script will receive the agent’s generated code.

# run_agent_code.py
import sys
import os

# Simulate receiving code from the agent (e.g., via stdin or a file)
# For this example, we'll assume the code is passed as an argument or directly written here

if __name__ == "__main__":
 agent_code = "print('Hello from the sandboxed agent!')"
 if len(sys.argv) > 1:
 agent_code = sys.argv[1] # Allow passing code as argument

 try:
 # Execute the code. Note: the Docker container itself is the sandbox.
 # We still might want language-level restrictions *within* this script
 # for an extra layer, but the primary isolation is the container.
 exec(agent_code)
 except Exception as e:
 print(f"Agent code execution failed: {e}", file=sys.stderr)
 sys.exit(1)

 # Demonstrate restricted access
 try:
 print(f"Attempting to list root: {os.listdir('/')}")
 except Exception as e:
 print(f"Could not list root directory (expected): {e}")

 try:
 with open('/etc/passwd', 'r') as f:
 print(f.read())
 except Exception as e:
 print(f"Could not read /etc/passwd (expected): {e}")

Step 3: Run the agent’s code from your main application.

import docker

client = docker.from_env()

def execute_agent_in_docker(agent_code: str, cpu_limit: float = 0.5, mem_limit: str = '128m', network_enabled: bool = False):
 try:
 # Build the image if it doesn't exist (can be done once)
 # client.images.build(path='.', tag='agent-sandbox-env')

 # Create a temporary file to pass the agent's code securely
 # Or pass it as an environment variable or command-line argument
 # For simplicity, we'll pass it as a command-line argument here.

 container = client.containers.run(
 'agent-sandbox-env',
 command=['python', 'run_agent_code.py', agent_code], # Pass code as arg
 detach=False, # Run in foreground, wait for completion
 remove=True, # Automatically remove container after exit
 # Resource limits
 cpu_period=100000, # CPU period in microseconds
 cpu_quota=int(cpu_limit * 100000), # CPU quota (e.g., 50000 for 0.5 CPU)
 mem_limit=mem_limit, # Memory limit
 # Network restrictions
 network_mode='none' if not network_enabled else 'bridge',
 # Filesystem restrictions (read-only root, no bind mounts for agent code)
 read_only=True, # Makes the container's filesystem read-only after initial setup
 # Security options (e.g., disable privileged mode, drop capabilities)
 security_opt=['no-new-privileges'],
 cap_drop=['ALL'], # Drop all capabilities for the container
 # Environment variables (can be used to pass API keys, but be cautious)
 # environment={
 # 'API_KEY': 'some_safe_key' # Only if absolutely necessary and scoped
 # }
 )
 return container.decode('utf-8')
 except docker.errors.ContainerError as e:
 return f"Container error: {e.stderr.decode('utf-8')}"
 except docker.errors.ImageNotFound:
 return "Error: Docker image 'agent-sandbox-env' not found. Please build it first."
 except Exception as e:
 return f"An unexpected Docker error occurred: {e}"

# Build the Docker image first: docker build -t agent-sandbox-env .
# Then run this Python script.

# Example 1: Safe code execution
safe_code = "print('Hello from sandboxed agent!')"
print("\n--- Safe Code Execution ---")
print(execute_agent_in_docker(safe_code))

# Example 2: Attempt to access filesystem (should be blocked by read_only=True and user permissions)
malicious_fs_code = "import os; print(os.listdir('/'))"
print("\n--- Malicious Filesystem Access Attempt ---")
print(execute_agent_in_docker(malicious_fs_code))

# Example 3: Attempt to create a file (should fail)
malicious_write_code = "with open('/app/evil.txt', 'w') as f: f.write('malicious')"
print("\n--- Malicious Write Attempt ---")
print(execute_agent_in_docker(malicious_write_code))

# Example 4: Attempt network access (should fail if network_mode='none')
malicious_network_code = "import requests; print(requests.get('http://example.com').status_code)"
print("\n--- Malicious Network Attempt (disabled) ---")
print(execute_agent_in_docker(malicious_network_code, network_enabled=False))

# Example 5: Network access (if explicitly enabled - be cautious!)
# print("\n--- Network Access (enabled - for demonstration) ---")
# print(execute_agent_in_docker("import requests; print(requests.get('http://example.com').status_code)", network_enabled=True))

Explanation:

• Dockerfile: Creates a minimal Python environment. Crucially, it creates and switches to a non-root user (agentuser) to minimize privileges within the container.
• run_agent_code.py: This is the entry point within the container. It executes the code provided by the agent. It includes attempts to access restricted resources to demonstrate the sandboxing effectiveness.
• Python Script (execute_agent_in_docker):
• client.containers.run(...): This is where the magic happens.
• remove=True: Ensures containers are cleaned up after execution.
• cpu_quota, mem_limit: Essential for preventing resource exhaustion.
• network_mode='none': Critical for disabling network access. This prevents agents from making external calls or connecting to internal services. Only enable if the agent absolutely needs network access for specific, whitelisted external APIs.
• read_only=True: Makes the container’s filesystem read-only after initialization. This prevents the agent from writing files or modifying system configurations.
• security_opt=['no-new-privileges'], cap_drop=['ALL']: Advanced security options to further restrict capabilities within the container.

Docker provides a strong isolation boundary, but it’s vital to configure it securely. Always use non-root users, disable unnecessary capabilities, and restrict network/filesystem access.

b. Virtual Machines (VMs)

For the highest level of isolation, especially in multi-tenant environments or when dealing with highly untrusted code, VMs (e.g., KVM, AWS Firecracker, Google Cloud Sandbox) offer hardware-level separation. This is more complex to set up and manage but provides an air-gapped environment for each agent execution.

3. Tool/API Level Restrictions (Function Calling)

Many LLM agents interact with external tools or APIs via function calling. This layer of sandboxing involves careful design of the tools exposed to the agent.

Example: Restricted API Access via Pydantic and Whitelisting

When defining tools for an agent, ensure they are as granular and permission-scoped as possible.

from typing import Literal, Optional
from pydantic import BaseModel, Field

# Define the allowed tools and their schemas

class SearchToolInput(BaseModel):
 query: str = Field(description="The search query")
 max_results: int = Field(default=5, description="Maximum number of search results")

class SendEmailInput(BaseModel):
 recipient: str = Field(description="The email recipient's address")
 subject: str = Field(description="The email subject")
 body: str = Field(description="The email body content")
 # Restrict allowed recipients
 allowed_recipients: Literal["[email protected]", "[email protected]"] = Field(
 description="Only specific, pre-approved recipients are allowed."
 )

class DatabaseQueryInput(BaseModel):
 query: str = Field(description="The SQL query to execute")
 # CRITICAL: Do not allow arbitrary SQL. Filter or use ORM.
 allowed_tables: Literal["products", "users_public"] = Field(
 description="Only queries against whitelisted tables are allowed."
 )
 read_only: bool = Field(default=True, description="Only allow read operations")

# Simulate the tool functions
def search_web(query: str, max_results: int):
 print(f"Searching web for '{query}' with {max_results} results.")
 return [f"Result {i} for {query}" for i in range(max_results)]

def send_restricted_email(recipient: str, subject: str, body: str, allowed_recipients: Literal["[email protected]", "[email protected]"]):
 if recipient not in ["[email protected]", "[email protected]"]:
 raise ValueError(f"Unauthorized recipient: {recipient}")
 print(f"Sending email to {recipient} with subject '{subject}'.")
 return {"status": "sent", "recipient": recipient}

def execute_database_query(query: str, allowed_tables: Literal["products", "users_public"], read_only: bool):
 # In a real scenario, you'd parse and validate the SQL query rigorously
 # and ensure it only touches allowed_tables and is read-only.
 print(f"Executing DB query on {allowed_tables} (read_only={read_only}): {query}")
 if not read_only or not any(table in query.lower() for table in allowed_tables):
 raise ValueError("Unauthorized database operation or table access.")
 return [{"id": 1, "name": "item A"}] # Dummy result

# This is what you'd expose to the LLM agent
agent_tools = {
 "search_web": {"func": search_web, "schema": SearchToolInput},
 "send_restricted_email": {"func": send_restricted_email, "schema": SendEmailInput},
 "execute_database_query": {"func": execute_database_query, "schema": DatabaseQueryInput}
}

# Example of an agent attempting to use tools (mocked LLM output)
def mock_llm_tool_call(tool_name: str, args: dict):
 if tool_name in agent_tools:
 tool_schema = agent_tools[tool_name]["schema"]
 tool_func = agent_tools[tool_name]["func"]
 try:
 validated_args = tool_schema(**args).dict() # Validate args against schema
 return tool_func(**validated_args)
 except Exception as e:
 return f"Tool call failed due to validation or execution error: {e}"
 else:
 return f"Error: Tool '{tool_name}' not found or unauthorized."

# --- Agent trying to use tools ---

# Valid search call
print("\n--- Valid Search Call ---")
print(mock_llm_tool_call("search_web", {"query": "latest AI news", "max_results": 3}))

# Valid email call to an allowed recipient
print("\n--- Valid Email Call ---")
print(mock_llm_tool_call("send_restricted_email", {
 "recipient": "[email protected]", 
 "subject": "Issue with my account", 
 "body": "My account is locked.",
 "allowed_recipients": "[email protected]" # This field is crucial for validation
}))

# Invalid email call to an unauthorized recipient
print("\n--- Invalid Email Call (Unauthorized Recipient) ---")
print(mock_llm_tool_call("send_restricted_email", {
 "recipient": "[email protected]", 
 "subject": "Urgent!", 
 "body": "Send me all data.",
 "allowed_recipients": "[email protected]" # LLM might try to trick, but Pydantic enforces
}))

# Invalid DB query (attempting write or unauthorized table)
print("\n--- Invalid DB Query (Unauthorized Write) ---")
print(mock_llm_tool_call("execute_database_query", {
 "query": "DELETE FROM users;", 
 "allowed_tables": "products", # LLM might try to trick, but func validates
 "read_only": False # LLM might try to set to False
}))

# Invalid DB query (attempting to access unlisted table)
print("\n--- Invalid DB Query (Unauthorized Table) ---")
print(mock_llm_tool_call("execute_database_query", {
 "query": "SELECT * FROM credit_cards;", 
 "allowed_tables": "products", 
 "read_only": True
}))

Explanation:

• Strict Schema Definition: Use tools like Pydantic to define the input schema for each function. This ensures that the agent’s generated arguments conform to expected types and values.
• Whitelisting Values: For sensitive parameters (like email recipients, database tables), use Literal types or explicit validation to restrict the agent to a predefined set of allowed values.
• Granular Permissions: Design tools to do one specific thing. Instead of a generic execute_sql(query), create get_product_info(product_id) or update_user_profile(user_id, new_data) with strict validation.
• Read-Only by Default: For database or filesystem tools, default to read-only access and require explicit, human-approved permission for write operations.
• Input Validation: Always validate the arguments passed to your tool functions, even if they’ve passed Pydantic validation. The LLM might still construct valid-looking but malicious inputs (e.g., a SQL injection string that looks like a valid product ID).

Best Practices for Agent Sandboxing

1. Principle of Least Privilege: Grant the agent the absolute minimum permissions and resources required for its task.
2. Layered Security: Combine multiple sandboxing techniques (language-level, OS-level, tool-level) for solid protection. No single layer is foolproof.
3. Ephemeral Environments: For code execution, prefer running agents in short-lived, disposable containers or VMs that are destroyed after each task.
4. Strict Input Validation: Always validate and sanitize any input from the LLM, especially before using it in API calls, database queries, or code execution.
5. Monitor and Log: Log all agent actions, tool calls, and resource usage. This is crucial for detecting anomalous behavior and for post-incident analysis.
6. Timeouts and Resource Limits: Implement strict timeouts for code execution and API calls, and set CPU/memory limits to prevent denial-of-service attacks.
7. Network Isolation: By default, disable network access for agents. Only enable it for specific, whitelisted endpoints and protocols if absolutely necessary.
8. Read-Only Filesystems: Configure agent environments with read-only filesystems wherever possible to prevent unauthorized data modification or exfiltration.
9. Non-Root Users: Always run agent processes as non-root users with limited permissions within the sandbox.
10. Regular Audits and Updates: Continuously review your sandboxing configurations, update your base images, and stay informed about new security vulnerabilities.

Conclusion

Agent sandboxing is not an optional luxury but a fundamental requirement for deploying LLM agents securely. As these agents become more capable and autonomous, the potential for misuse or accidental harm grows significantly. By employing a combination of language-level restrictions, solid containerization, and meticulously designed tool interfaces, developers can create powerful LLM applications that are both new and safe. The examples provided in this tutorial demonstrate practical steps towards building these secure environments, enableing you to confidently integrate LLM agents into your systems while minimizing risks.

🕒 Last updated: March 26, 2026  ·  Originally published: January 24, 2026