# How SandboxManager Selects the Platform Backend for Sandboxing in Apache Maka

> Learn how SandboxManager selects a platform backend for sandboxing in Apache Maka. Discover its three-step decision process for secure command execution.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: internals
- Published: 2026-09-05

---

**SandboxManager** uses a three-step decision process—checking if sandboxing is required, selecting a platform-matched backend, and verifying availability—to determine which sandbox backend to use for executing commands securely.

The **Apache Maka** runtime includes a robust sandboxing system that isolates untrusted code execution. At its core, the `SandboxManager` class orchestrates backend selection based on caller preferences, permission profiles, and the underlying operating system. This article explains the complete selection mechanism as implemented in the source code.

## Step 1: Determine If Sandboxing Is Required

Before selecting any backend, `SandboxManager` evaluates whether sandboxing is actually necessary. This logic lives in `shouldSandbox`, located in [`packages/runtime/src/sandbox/sandbox-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/sandbox-manager.ts) (lines 42–50).

The method accepts two inputs:

- **`preference`**: A caller-provided enum with values `'auto'`, `'require'`, or `'forbid'`
- **`profile`**: A permission profile describing file-system and network restrictions

The decision tree works as follows:

| Preference | Behavior |
|------------|----------|
| `forbid` | Never sandbox; returns `false` immediately |
| `require` | Always sandbox; returns `true` immediately |
| `auto` | Delegates to `profileRequiresSandbox(profile)` |

For `auto` mode, the system sandboxes when the profile indicates a **managed profile with restricted file-system or network access**. Here's the implementation:

```ts
// sandbox-manager.ts: lines 42-50
if (preference === 'forbid') return false;
if (preference === 'require') return true;
return profileRequiresSandbox(profile);

```

This early exit prevents unnecessary backend selection work when sandboxing is explicitly disabled or when unrestricted permissions make isolation redundant.

## Step 2: Select the Initial Backend Based on Platform

When `shouldSandbox` returns `true`, `selectInitial` chooses a backend matching the current platform. The platform is determined from `process.platform` or an optional caller override.

The selection logic in [`packages/runtime/src/sandbox/sandbox-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/sandbox-manager.ts) maps each supported OS to a specific backend type:

### macOS Selection (Lines 68–78, 80–88)

For `darwin` platforms, the manager requires the `macos-seatbelt` backend:

```ts
// sandbox-manager.ts: lines 68-78
case 'darwin': {
  if (this.backends.has('macos-seatbelt')) {
    return {
      ok: true,
      sandboxType: 'macos-seatbelt',
      platform: 'darwin',
    };
  }
  // Fall through to unsupported_platform error (lines 80-88)
}

```

If `macos-seatbelt` isn't registered in `this.backends`, the manager returns a failure with `reason: 'unsupported_platform'`.

### Linux Selection (Lines 91–101, 103–111)

For `linux` platforms, the manager selects the `linux` backend:

```ts
// sandbox-manager.ts: lines 91-101
case 'linux': {
  if (this.backends.has('linux')) {
    return {
      ok: true,
      sandboxType: 'linux',
      platform: 'linux',
    };
  }
  // Fall through to unsupported_platform error (lines 103-111)
}

```

### Windows Selection (Lines 114–124, 126–134)

For `win32` platforms, the manager selects the `windows` backend:

```ts
// sandbox-manager.ts: lines 114-124
case 'win32': {
  if (this.backends.has('windows')) {
    return {
      ok: true,
      sandboxType: 'windows',
      platform: 'win32',
    };
  }
  // Fall through to unsupported_platform error (lines 126-134)
}

```

### Unsupported Platforms

Any platform not matching `darwin`, `linux`, or `win32` triggers an immediate `unsupported_platform` failure.

## Step 3: Verify Backend Availability and Capability

After `selectInitial` returns a candidate backend, the manager performs additional validation before actual use. This verification happens in `canEnforce` or during the subsequent `transform` call (lines 48–55).

The checks include:

1. **Backend presence**: The selected backend exists in `this.backends`
2. **Platform availability**: Optional `isAvailable(platform)` returns `true`
3. **Profile enforcement**: Optional `canEnforceProfile(profile)` returns `true`

```ts
// sandbox-manager.ts: lines 48-55
const backend = this.backends.get(selection.sandboxType);
if (!backend) return false;

if (!(backend.isAvailable?.(selected.platform) ?? true)) return false;
return backend.canEnforceProfile?.(input.profile) ?? true;

```

Failures at this stage produce `backend_not_available` or `unsupported_platform` errors, giving callers precise diagnostic information.

## Practical Example: Registering and Selecting a Backend

Here's a complete workflow demonstrating backend registration and selection:

```ts
import { SandboxManager } from '@maka/runtime/src/sandbox/sandbox-manager.js';
import { LinuxBubblewrapBackend } from '@maka/runtime/src/sandbox/linux-sandbox.js';

// Register a Linux backend
const manager = new SandboxManager([
  new LinuxBubblewrapBackend({
    capability: { available: true, bwrapPath: '/usr/bin/bwrap' },
  }),
]);

// Prepare a restricted permission profile (e.g., workspace-write)
import { createWorkspaceWritePermissionProfile } from '@maka/core/permission-profile';

const profile = createWorkspaceWritePermissionProfile();

// Ask the manager to pick a backend for the current platform (Linux here)
const selection = manager.selectInitial({ profile, platform: 'linux' });

if (selection.ok) {
  console.log('Chosen backend:', selection.sandboxType); // → "linux"
} else {
  console.error('Failed to select backend:', selection.reason);
}

```

Once selected, transform commands for sandboxed execution:

```ts
// Transform a command using the selected backend
const result = manager.transform({
  command: {
    program: '/bin/ls',
    args: ['-l', '/tmp'],
    cwd: '/repo',
    profile,
    pathContext: { workspaceRoots: ['/repo'], slashTmp: '/tmp' },
  },
  platform: 'linux',
});

if (result.ok) {
  console.log('Exec argv:', result.exec.argv);
} else {
  console.error('Transform error:', result.reason);
}

```

## Key Files in the Sandbox Selection Architecture

| File | Role |
|------|------|
| [`packages/runtime/src/sandbox/sandbox-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/sandbox-manager.ts) | Core logic for sandbox selection, enforcement checks, and transformation |
| [`packages/runtime/src/sandbox/types.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/types.ts) | Type definitions (`SandboxType`, `SandboxSelectionInput`, `SandboxBackend`) |
| [`packages/runtime/src/__tests__/sandbox-manager.test.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/__tests__/sandbox-manager.test.ts) | Unit tests illustrating selection rules for all platforms |
| [`packages/runtime/src/sandbox/linux-sandbox.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/linux-sandbox.ts) | Example Linux backend (`LinuxBubblewrapBackend`) |
| [`packages/runtime/src/sandbox/sandbox-denial.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/sandbox-denial.ts) | Helper for representing denied sandbox scenarios |

## Summary

- **Requirement check**: `shouldSandbox` uses preference (`auto`/`require`/`forbid`) and profile restrictions to decide if sandboxing is needed
- **Platform matching**: `selectInitial` maps `darwin` → `macos-seatbelt`, `linux` → `linux`, `win32` → `windows`
- **Registration dependency**: Each backend must be registered in the `SandboxManager` constructor via `this.backends`
- **Runtime verification**: `isAvailable` and `canEnforceProfile` validate the backend can actually enforce the requested profile
- **Clear failure modes**: The system returns structured errors (`unsupported_platform`, `backend_not_available`) for debugging

## Frequently Asked Questions

### What happens if the required backend isn't registered?

The manager returns a failure result with `reason: 'unsupported_platform'` and `ok: false`. This occurs in `selectInitial` when `this.backends.has(sandboxType)` returns false for the detected platform (lines 80–88, 103–111, and 126–134).

### Can I force sandboxing even for unrestricted profiles?

Yes. Pass `preference: 'require'` to `shouldSandbox`. This bypasses the `profileRequiresSandbox` check and always returns `true`, causing the manager to proceed with backend selection regardless of profile permissions.

### How does the manager handle unknown platforms?

Any platform string not matching `darwin`, `linux`, or `win32` falls through to a default case that returns `unsupported_platform`. The manager does not attempt to guess or polyfill backends for unsupported operating systems.

### What is the difference between `selectInitial` and `transform`?

`selectInitial` performs platform-based backend selection and returns a `SandboxSelectionResult`. `transform` takes that selection and produces the actual command-line arguments needed to run a specific program inside the sandbox, including all isolation flags and bind mounts.