# Maka Sandbox Requirements: Rules for Requiring a Platform Sandbox

> Discover Maka's platform sandbox requirements. Learn the three key conditions that trigger a sandbox when permission profiles are managed and policies are restricted.

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

---

**Maka requires a platform sandbox only when three conditions align: the permission profile is managed, its filesystem or network policy is restricted, and the sandbox preference is not set to forbid.**

Maka's security model centers on **permission profiles** that govern runtime access to system resources. The Apache Maka project implements a predictable, fail-closed mechanism for determining when to invoke platform-specific sandboxes on macOS (Seatbelt), Linux (Bubblewrap), or Windows (AppContainer). Understanding these rules is essential for developers configuring secure execution environments.

## Profile Type: Only Managed Profiles Qualify

The sandbox decision begins with profile classification. Maka recognizes three profile types, but only **managed profiles** can trigger sandboxing.

- **Managed profiles**: Active permission configurations with explicit resource policies.
- **Unmanaged / disabled profiles**: Inactive configurations that never require sandboxing.
- **External profiles**: Third-party or delegated configurations that bypass sandbox checks.

As implemented in [`packages/runtime/src/sandbox/sandbox-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/sandbox-manager.ts), the `profileRequiresSandbox` helper explicitly guards against non-managed types:

```typescript
if (profile.type !== 'managed') return false;       // only managed profiles matter

```

## Policy Restrictions: Filesystem and Network Drive the Decision

For managed profiles, Maka examines two policy domains: **filesystem** and **network**. Either domain being `restricted` forces a sandbox requirement.

The core logic resides in `profileRequiresSandbox` at lines 204–207:

```typescript
export function profileRequiresSandbox(profile: PermissionProfile): boolean {
  if (profile.type !== 'managed') return false;
  return (
    profile.fileSystem.kind === 'restricted' ||       // restricted FS → sandbox
    profile.network.kind === 'restricted'            // restricted network → sandbox
  );
}

```

| Policy Domain | Kind | Sandbox Required? |
|-------------|------|-----------------|
| Filesystem | `restricted` | Yes |
| Filesystem | `unrestricted` | No (unless network is restricted) |
| Network | `restricted` | Yes |
| Network | `unrestricted` | No (unless filesystem is restricted) |

This OR-based semantics means a profile with unrestricted filesystem but restricted networking still demands sandboxing.

## Sandbox Preference: Auto, Require, or Forbid

Users and tools can override default behavior through the **sandbox preference**, defined in [`packages/runtime/src/sandbox/types.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/types.ts). The `SandboxablePreference` type accepts three values:

- **`auto`** (default): Sandbox only if `profileRequiresSandbox` returns true.
- **`require`**: Force sandbox regardless of profile configuration.
- **`forbid`**: Disable sandboxing even when the profile demands it.

The `shouldSandbox` method in `SandboxManager` implements this precedence:

```typescript
shouldSandbox(
  profile: PermissionProfile,
  preference: SandboxablePreference = 'auto',
  _platform: SandboxPlatform = process.platform,
): boolean {
  if (preference === 'forbid') return false;          // explicit disable
  if (preference === 'require') return true;          // explicit enable
  return profileRequiresSandbox(profile);             // default rule
}

```

Preference evaluation short-circuits: `forbid` and `require` intercept before profile inspection.

## Platform Backend Availability and Fail-Closed Behavior

Once sandboxing is deemed necessary, `SandboxManager.selectInitial` attempts backend selection based on `process.platform`. The mapping is:

| Platform | Backend |
|----------|---------|
| `darwin` | `macos-seatbelt` ([`packages/runtime/src/sandbox/macos-seatbelt.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/macos-seatbelt.ts)) |
| `linux` | `linux` ([`packages/runtime/src/sandbox/linux-sandbox.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/linux-sandbox.ts)) |
| `win32` | `windows` ([`packages/runtime/src/sandbox/windows-sandbox.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/windows-sandbox.ts)) |

If the corresponding backend is not registered or unavailable, Maka **fails closed** with `backend_not_available`. Unsupported platforms return `unsupported_platform`. This design prevents accidental unsandboxed execution when security boundaries are expected.

## Practical Code Examples

### Automatic Sandbox Trigger with Restricted Profile

```typescript
import { SandboxManager } from '@maka/runtime/sandbox';
import { PermissionProfile } from '@maka/core/permission-profile';

const restrictedProfile: PermissionProfile = {
  type: 'managed',
  fileSystem: { kind: 'restricted', readOnly: true, paths: ['/workspace'] },
  network: { kind: 'unrestricted' },
};

const manager = new SandboxManager();
const needsSandbox = manager.shouldSandbox(restrictedProfile);
// Result: true (filesystem is restricted)

```

### Explicit Preference Override

```typescript
// Force sandbox regardless of profile
const forced = manager.shouldSandbox(unrestrictedProfile, 'require'); // true

// Prevent sandbox regardless of profile
const blocked = manager.shouldSandbox(restrictedProfile, 'forbid');   // false

```

### Unrestricted Managed Profile Bypasses Sandbox

```typescript
const unrestrictedProfile: PermissionProfile = {
  type: 'managed',
  fileSystem: { kind: 'unrestricted' },
  network: { kind: 'unrestricted' },
};

const needsSandbox = manager.shouldSandbox(unrestrictedProfile); // false

```

### Handling Sandbox Enforcement in Tools

```typescript
if (!manager.canEnforce({ profile, preference: 'auto' })) {
  // Backend unavailable or unsupported — escalate to user
  await tools.request_sandbox_boundary({ expansion: 'workspace-write' });
}

```

## Key Source Files

| File | Purpose |
|------|---------|
| [`packages/runtime/src/sandbox/sandbox-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/sandbox-manager.ts) | Core decision logic: `shouldSandbox`, `selectInitial`, `profileRequiresSandbox` |
| [`packages/runtime/src/sandbox/types.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/types.ts) | Type definitions for `SandboxablePreference`, result structures |
| [`packages/runtime/src/sandbox/macos-seatbelt.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/macos-seatbelt.ts) | macOS `sandbox-exec` wrapper implementation |
| [`packages/runtime/src/sandbox/linux-sandbox.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/linux-sandbox.ts) | Linux Bubblewrap namespace and seccomp builder |
| [`packages/runtime/src/sandbox/windows-sandbox.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/windows-sandbox.ts) | Windows AppContainer launch implementation |
| [`packages/runtime/src/sandbox/README.md`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/README.md) | High-level architecture and configuration documentation |

## Summary

- **Managed + restricted policy** → sandbox required under `auto` preference.
- **Unrestricted, disabled, or external profiles** → no sandbox triggered.
- **Preference `require`** → unconditional sandbox; **`forbid`** → unconditional bypass.
- **Missing backend or unsupported platform** → operation fails closed with explicit error codes.
- All rules derive from [`packages/runtime/src/sandbox/sandbox-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/sandbox-manager.ts) with backend selection in `selectInitial`.

## Frequently Asked Questions

### What happens if a restricted profile runs on an unsupported platform?

Maka returns `unsupported_platform` and fails closed. The sandbox is not silently skipped—execution halts with an error, preventing accidental security degradation.

### Can I sandbox an unmanaged or external profile using the `require` preference?

Yes. The `require` preference bypasses profile type checks entirely. Any profile—managed, unmanaged, or external—will attempt sandboxing when preference is set to `require`, subject to backend availability.

### Why does Maka use OR logic for filesystem and network policies rather than AND?

The OR design ensures defense-in-depth. Restricting either communication surface (disk I/O or network) represents a security boundary worth enforcing. Requiring both would leave hybrid-risk profiles unsandboxed.

### Where is the sandbox preference typically configured?

The preference flows from tool configuration or runtime environment variables into `SandboxManager.shouldSandbox`. According to [`packages/runtime/src/sandbox/README.md`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/README.md), tools may expose this as CLI flags (`--sandbox=auto|require|forbid`) or workspace settings.