Cross-Platform Compatibility Guide¶

from isolated_agents_sdk import run_agent, Policy

def my_agent():
    print("Running on Linux with full features!")
    return {"status": "success"}

result = run_agent(
    agent=my_agent,
    working_dir="./workspace",
    policy=Policy(
        cpu_cores=2.0,
        memory_mb=1024,
        network=NetworkPolicy(disabled=False),
    )
)

from isolated_agents_sdk import run_agent, Policy
import platform

def my_agent():
    print(f"Running on {platform.system()}")
    return {"status": "success", "platform": "macOS"}

result = run_agent(
    agent=my_agent,
    working_dir="./workspace",
    policy=Policy(
        cpu_cores=2.0,
        memory_mb=1024,
        # Security features gracefully degrade on macOS
        cap_drop=["ALL"],  # Ignored on macOS
        seccomp_profile=None,  # Not available on macOS
    )
)

from isolated_agents_sdk import run_agent
from pathlib import Path

# Windows path
working_dir = Path("C:/Users/username/workspace")

# SDK converts to WSL2 path automatically
result = run_agent(
    agent=my_agent,
    working_dir=working_dir,  # Converted to /mnt/c/Users/username/workspace
    policy=Policy()
)

from isolated_agents_sdk import run_agent, Policy
import platform

def my_agent():
    print(f"Running on {platform.system()}")
    return {"status": "success", "platform": "Windows"}

# Use forward slashes or Path objects
result = run_agent(
    agent=my_agent,
    working_dir="./workspace",  # Works on all platforms
    policy=Policy(
        cpu_cores=2.0,
        memory_mb=1024,
    )
)

from pathlib import Path

# Good - works on all platforms
working_dir = Path("./workspace")
output_dir = Path.home() / "output"

# Bad - Windows-specific
working_dir = "C:\\workspace"  # Fails on Linux/macOS

# Good - works everywhere
policy = Policy(output_path_in_container="/output")

# Bad - backslashes don't work in containers
policy = Policy(output_path_in_container="\\output")

import shutil

def detect_runtime():
    """Detect available container runtime."""
    if shutil.which("podman"):
        return "podman"
    elif shutil.which("docker"):
        return "docker"
    else:
        raise RuntimeError("No container runtime found")

runtime = detect_runtime()
print(f"Using {runtime}")

import platform
from isolated_agents_sdk import Policy

def create_policy():
    """Create platform-appropriate policy."""
    is_linux = platform.system() == "Linux"

    return Policy(
        cpu_cores=2.0,
        memory_mb=1024,
        # Linux-specific security features
        cap_drop=["ALL"] if is_linux else [],
        seccomp_profile="default.json" if is_linux else None,
        read_only_rootfs=is_linux,  # Best on Linux
    )

policy = create_policy()

import platform

def get_working_dir():
    """Get optimal working directory for platform."""
    system = platform.system()

    if system == "Linux":
        # Use any directory
        return "./workspace"
    elif system == "Darwin":  # macOS
        # Use home directory for better performance
        return str(Path.home() / "workspace")
    elif system == "Windows":
        # Use WSL2 filesystem if available
        wsl_path = Path("/mnt/c/workspace")
        if wsl_path.exists():
            return str(wsl_path)
        return "./workspace"

    return "./workspace"

import os

# Good - works on all platforms
api_key = os.environ.get("OPENAI_API_KEY")

# Good - set environment variables
os.environ["MY_VAR"] = "value"

# Bad - platform-specific syntax
# Don't use $VAR or %VAR% in code

from isolated_agents_sdk.adapters.factory import AdapterFactory

# Use Podman
podman_adapter = AdapterFactory.create_container_adapter("podman")

# Use Docker
docker_adapter = AdapterFactory.create_container_adapter("docker")

# Use Kubernetes
k8s_adapter = AdapterFactory.create_container_adapter("kubernetes")

# Auto-detect
auto_adapter = AdapterFactory.create_container_adapter("auto")

# Use pathlib for automatic conversion
from pathlib import Path

# Good
working_dir = Path("./workspace")

# Bad
working_dir = "C:\\workspace"

"""Platform detection and configuration utilities."""

import platform
import shutil
from pathlib import Path
from typing import Optional


class PlatformInfo:
    """Platform information and capabilities."""

    def __init__(self):
        self.system = platform.system()
        self.is_linux = self.system == "Linux"
        self.is_macos = self.system == "Darwin"
        self.is_windows = self.system == "Windows"
        self.architecture = platform.machine()

    def detect_container_runtime(self) -> Optional[str]:
        """Detect available container runtime."""
        if shutil.which("podman"):
            return "podman"
        elif shutil.which("docker"):
            return "docker"
        return None

    def supports_cgroups_v2(self) -> bool:
        """Check if cgroups v2 is available."""
        if not self.is_linux:
            return False
        return Path("/sys/fs/cgroup/cgroup.controllers").exists()

    def supports_rootless(self) -> bool:
        """Check if rootless containers are supported."""
        return self.is_linux

    def get_optimal_working_dir(self, base_dir: str = "./workspace") -> Path:
        """Get optimal working directory for platform."""
        if self.is_linux:
            return Path(base_dir)
        elif self.is_macos:
            return Path.home() / "workspace"
        elif self.is_windows:
            # Prefer WSL2 filesystem
            wsl_path = Path("/mnt/c/workspace")
            if wsl_path.exists():
                return wsl_path
            return Path(base_dir)
        return Path(base_dir)


# Global instance
platform_info = PlatformInfo()