Maka Sandbox Requirements: Rules for Requiring a Platform Sandbox

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, the profileRequiresSandbox helper explicitly guards against non-managed types:

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:

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. 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:

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)
linux	linux (packages/runtime/src/sandbox/linux-sandbox.ts)
win32	windows (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

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

// 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

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

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

Handling Sandbox Enforcement in Tools

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	Core decision logic: shouldSandbox, selectInitial, profileRequiresSandbox
packages/runtime/src/sandbox/types.ts	Type definitions for SandboxablePreference, result structures
packages/runtime/src/sandbox/macos-seatbelt.ts	macOS sandbox-exec wrapper implementation
packages/runtime/src/sandbox/linux-sandbox.ts	Linux Bubblewrap namespace and seccomp builder
packages/runtime/src/sandbox/windows-sandbox.ts	Windows AppContainer launch implementation
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 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, tools may expose this as CLI flags (--sandbox=auto|require|forbid) or workspace settings.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}