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:

PYISOLATE_ENABLE_CUDA_IPC=1 environment variable
Same CUDA version in host and extension
Same GPU device visible to both processes
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