pyisolate/docs/platform_compatibility.md

Platform Compatibility Matrix

This document describes pyisolate's compatibility across different platforms, operating systems, and configurations.

Operating System Support

OS	Sandbox	Tensor IPC	Notes
Linux (glibc)	✅ Full	✅ Full	Primary supported platform
Linux (musl/Alpine)	✅ Full	✅ Full	Requires bubblewrap
Ubuntu 22.04+	⚠️ Degraded	✅ Full	AppArmor restricts user namespaces
Ubuntu 20.04	✅ Full	✅ Full
Debian 11+	✅ Full	✅ Full
RHEL/CentOS 8+	✅ Full	✅ Full
Fedora	✅ Full	✅ Full	SELinux may need configuration
macOS	❌ None	⚠️ Limited	No namespace support
Windows	❌ None	❌ None	Use WSL2
WSL2	⚠️ Varies	✅ Full	Depends on kernel version

Legend

• ✅ Full: All features work as designed
• ⚠️ Degraded/Limited: Some features unavailable or restricted
• ❌ None: Feature not supported

Sandbox Mode Details

Linux with Full Support

RestrictionModel.NONE

Full sandbox capabilities available:

• User namespace isolation
• PID namespace isolation
• Filesystem mount namespace
• Network isolation (optional)

Ubuntu 22.04+ (AppArmor Restricted)

RestrictionModel.APPARMOR

Ubuntu's AppArmor profile restricts bubblewrap's --unshare-user flag. PyIsolate automatically detects this and runs in degraded mode:

from pyisolate._internal.sandbox_detect import detect_restriction_model, RestrictionModel

model = detect_restriction_model()
if model == RestrictionModel.APPARMOR:
    print("Running in degraded sandbox mode")

Impact:

• No user namespace isolation
• Filesystem isolation still works
• Process runs as current user

Workaround (requires root):

# Disable AppArmor for bwrap (not recommended for production)
sudo ln -s /etc/apparmor.d/bwrap /etc/apparmor.d/disable/
sudo apparmor_parser -R /etc/apparmor.d/bwrap

macOS

macOS does not support Linux namespaces. PyIsolate runs without sandbox:

SandboxMode.DISABLED

Extensions run in the same environment as the host process with no isolation.

Tensor IPC Compatibility

CPU Tensor Transfer

Platform	Method	Performance
Linux	POSIX shared memory (/dev/shm)	✅ Zero-copy
Linux (no /dev/shm)	File-based fallback	⚠️ Copy required
macOS	File-based	⚠️ Copy required
Windows (native)	Not supported	❌
WSL2	POSIX shared memory	✅ Zero-copy

CUDA Tensor Transfer

Platform	Method	Performance
Linux + NVIDIA GPU	CUDA IPC handles	✅ Zero-copy
macOS + Apple Silicon	Not supported	❌
Windows (native)	Not supported	❌
WSL2 + NVIDIA GPU	CUDA IPC	✅ Zero-copy

Requirements for CUDA IPC:

1. PYISOLATE_ENABLE_CUDA_IPC=1 environment variable
2. Same CUDA version in host and extension
3. Same GPU device visible to both processes
4. Sufficient GPU memory

Python Version Compatibility

Python Version	Status	Notes
3.12	✅ Supported	Primary development version
3.11	✅ Supported
3.10	✅ Supported
3.9	⚠️ Limited	May lack some type annotations
3.8	❌ Not supported	Missing required features

PyTorch Version Compatibility

PyTorch Version	Status	Notes
2.x	✅ Supported	Recommended
1.13	⚠️ Limited	IPC API differences
1.12	⚠️ Limited	Some tensor operations differ
< 1.12	❌ Not supported

Container Support

Docker

Configuration	Sandbox	Notes
Default	❌ None	Lacks required capabilities
--privileged	✅ Full	Full capabilities, less secure
--cap-add SYS_ADMIN	✅ Full	Minimal required capability
--security-opt apparmor=unconfined	⚠️ Varies	Depends on base image

Recommended Docker configuration:

# In docker run:
docker run --cap-add SYS_ADMIN --security-opt seccomp=unconfined ...

Kubernetes

For Kubernetes pods:

securityContext:
  capabilities:
    add:
      - SYS_ADMIN
  seccompProfile:
    type: Unconfined

Note: Many Kubernetes clusters restrict these capabilities for security reasons.

Hardware Requirements

Minimum

• 2GB RAM
• 100MB /dev/shm space
• Single CPU core

Recommended for GPU Workloads

• 8GB+ RAM
• 1GB+ /dev/shm space
• NVIDIA GPU with 4GB+ VRAM
• NVIDIA driver 470+
• CUDA 11.x or 12.x

Feature Detection

Use these utilities to check platform capabilities at runtime:

from pyisolate._internal.sandbox_detect import (
    detect_restriction_model,
    RestrictionModel,
)

# Check sandbox capability
model = detect_restriction_model()
print(f"Restriction model: {model}")

if model == RestrictionModel.NONE:
    print("Full sandbox support available")
elif model == RestrictionModel.APPARMOR:
    print("Running with AppArmor restrictions")
elif model == RestrictionModel.SYSCTL:
    print("User namespaces disabled via sysctl")

# Check /dev/shm
from pyisolate._internal.tensor_serializer import _check_shm_availability
if _check_shm_availability():
    print("/dev/shm available for tensor IPC")

# Check CUDA IPC
import os
if os.environ.get("PYISOLATE_ENABLE_CUDA_IPC") == "1":
    try:
        import torch
        if torch.cuda.is_available():
            print("CUDA IPC enabled")
    except ImportError:
        print("PyTorch not available")

Troubleshooting Platform Issues

Linux: Enable User Namespaces

# Check current setting
cat /proc/sys/kernel/unprivileged_userns_clone

# Enable (requires root)
sudo sysctl -w kernel.unprivileged_userns_clone=1

# Make persistent
echo 'kernel.unprivileged_userns_clone=1' | sudo tee /etc/sysctl.d/99-userns.conf

Ubuntu: Check AppArmor Status

# Check if bwrap is restricted
aa-status | grep bwrap

# Check current AppArmor mode
cat /sys/module/apparmor/parameters/enabled

Docker: Verify Capabilities

# Inside container
capsh --print | grep cap_sys_admin

WSL2: Check Kernel Version

uname -r
# Should be 5.10+ for best compatibility