vsbox

Sandboxed Python virtual environments — filesystem-isolated venvs for untrusted code.

vsbox is a standalone tool that creates Python virtual environments restricted to their own directory. It installs alongside (not replacing) virtualenv, venv, or any other environment manager.

Install

uv pip install git+https://github.com/mindsdb/vsbox.git

This installs the vsbox command. Your existing virtualenv / python -m venv are untouched.

Quick start

# Create a sandboxed venv
vsbox myenv

# Activate it (Python audit hooks are already active)
source myenv/bin/activate

# Or run with OS-level sandboxing too
myenv/bin/python-sandboxed script.py

How it works

vsbox creates a normal virtualenv, then installs three layers of filesystem restriction:

1. Python audit hooks (cross-platform, always active)

Every Python process in the venv automatically loads an audit hook via sys.addaudithook (PEP 578) that intercepts filesystem calls (open, os.listdir, os.rename, shutil.move, etc.) and blocks access outside the venv directory.

This is defense-in-depth — it catches all pure-Python filesystem access but can be bypassed by C extensions or ctypes.

2. macOS sandbox-exec (kernel-level)

On macOS, vsbox generates a bin/python-sandboxed wrapper that runs Python under Apple's sandbox-exec with a restrictive profile. The kernel denies all filesystem access except: the venv directory (read/write), the Python installation (read-only), system libraries (read-only), and temp directories.

3. Linux Landlock & bubblewrap (kernel-level)

On Linux, bin/python-sandboxed auto-detects the best available mechanism:

• Landlock (Linux 5.13+): Kernel syscalls directly, no extra tools needed
• bubblewrap: Namespace-based sandboxing, install with sudo apt install bubblewrap

4. Windows AppContainer (kernel-level)

On Windows 8+, Scripts\python-sandboxed.cmd runs Python inside a Windows AppContainer — a lightweight sandbox that restricts filesystem access at the kernel level. The AppContainer profile is created automatically on first use and grants access only to the venv directory, the Python installation, and any extra allowed paths.

Options

vsbox myenv                            # create sandboxed venv
vsbox myenv --mode log                 # warn but don't block (debugging)
vsbox myenv --allow /data              # allow read/write access to /data
vsbox myenv --allow /data --allow /nfs # multiple extra paths
vsbox myenv --allow-read /models       # allow read-only access to /models
vsbox myenv --allow-read /data --allow /out  # read /data, read+write /out
vsbox myenv --no-os-sandbox            # Python audit hooks only
vsbox myenv -p python3.11             # use a specific Python
vsbox myenv --no-pip                   # skip pip installation
vsbox myenv --clear                    # recreate from scratch

Configuration

After creation, edit myenv/sandbox/sandbox.json:

{
  "venv_root": "/path/to/myenv",
  "mode": "enforce",
  "allowed_paths": ["/data", "/shared"],
  "read_only_paths": ["/models", "/config"]
}

The macOS sandbox profile can be customized at myenv/sandbox/sandbox.sb.

Files installed into the venv

File	Purpose
lib/.../site-packages/_sandbox.pth	Auto-loads the audit hook on Python startup
lib/.../site-packages/_sandbox_hook.py	The audit hook implementation
lib/.../site-packages/_sandbox.json	Audit hook configuration
bin/python-sandboxed	OS-level sandbox wrapper script
bin/activate_sandboxed	Activation helper with sandbox info
sandbox/sandbox.json	Main sandbox configuration
sandbox/sandbox.sb	macOS sandbox-exec profile (macOS only)
sandbox/landlock_wrapper.py	Landlock wrapper (Linux only)
sandbox/bwrap_run.sh	bubblewrap wrapper (Linux only)
sandbox/windows_launcher.py	AppContainer launcher (Windows only)

Compatibility

• Works with any Python 3.8+
• Installs alongside virtualenv, venv, pyenv, uv, conda — no conflicts
• macOS, Linux, and Windows supported