What Is the Sandbox Boundary Language in Apache Maka? Purpose and Implementation Guide

The sandbox boundary language in Apache Maka is a formal, platform-neutral specification that defines what a session is allowed to do, how those permissions are enforced at runtime, and the exact process for user-approved expansions.

Maka's sandbox boundary language sits at the heart of its security architecture. This article explains its three core roles—permission modeling, boundary enforcement, and user-controlled expansion—by examining the actual source code in apache/maka.

What the Sandbox Boundary Language Defines

The language provides a complete, serializable description of sandbox permissions that works identically across macOS, Linux, and Windows. It resides primarily in packages/core/src/sandbox-boundary.ts.

Core Data Structures

Three immutable types form the foundation:

• SandboxBoundaryExpansion — describes desired filesystem entries and network access
• SandboxBoundaryRequest — carries the user's justification for expansion
• SandboxBoundaryResponse — records the host's allow/deny decision

export interface SandboxBoundaryFilesystemEntry {
  readonly path: string;
  readonly access: SandboxBoundaryAccess;
  readonly scope: SandboxBoundaryScope;
}

Source: packages/core/src/sandbox-boundary.ts

These types are intentionally read-only and versioned, ensuring that every boundary state is auditable and recoverable after crashes or restarts.

Role 1: Permission Model (What Is Allowed)

The permission model decouples the description of access from its enforcement. Constants like SANDBOX_BOUNDARY_ACCESS_MODES define the valid vocabulary for permissions, while helper functions validate expansions before they reach the user.

Validating an Expansion

import { validateSandboxBoundaryExpansion } from '@maka/core';

const result = validateSandboxBoundaryExpansion(expansion);
if (!result.ok) {
  throw new Error(`Invalid expansion: ${result.message}`);
}

Source: validateSandboxBoundaryExpansion, lines 13-51 of sandbox-boundary.ts

This validation ensures that malformed or contradictory permissions never reach the runtime. The function checks path sanitization, access mode compatibility, and scope validity.

Role 2: Boundary Enforcement (How It Is Enforced)

The ExecutionBoundary is the runtime's authoritative view of current sandbox constraints. It exists in three variants:

Boundary Type	Use Case
managed	Full sandboxing with OS-specific backend
bypass	Direct host execution (dangerous, requires justification)
external	Pre-validated, externally managed environment

Source: packages/runtime/src/sandbox/README.md

The runtime selects platform-specific backends—Seatbelt on macOS, bubblewrap on Linux, AppContainer on Windows—without changing the boundary language semantics.

Checking Path Permissions at Runtime

import { sandboxBoundaryExpansionAllowsPath } from '@maka/core';

const canRead = sandboxBoundaryExpansionAllowsPath(
  currentBoundary.expansion,
  '/home/user/file.txt',
  'read',
);

Source: sandboxBoundaryExpansionAllowsPath, lines 70-81 of sandbox-boundary.ts

This function is consulted by SandboxManager in packages/runtime/src/sandbox/sandbox-manager.ts before any tool executes a filesystem operation.

Role 3: User-Approved Expansion (When Permissions Change)

The sandbox boundary language specifies a strict protocol for permission changes. No running turn can expand its own boundary unilaterally—it must request approval through a structured flow.

Creating a Boundary Request

import { createGenesisExecutionBoundary } from '@maka/core';
import type { SandboxBoundaryExpansion } from '@maka/core';

const expansion: SandboxBoundaryExpansion = {
  filesystem: {
    entries: [
      { path: '/home/user', access: 'read', scope: 'subtree' },
    ],
  },
  network: { enabled: true },
};

const request = {
  sessionId: 'sess-123',
  requestId: 'req-456',
  turnId: 'turn-789',
  expansion,
  justification: 'Tool needs to read project files and call external API',
};

Source: CreateSandboxBoundaryRequest type in packages/core/src/sandbox-boundary.ts

The sandbox-boundary-tool.ts module handles persisting this request, presenting it to the user, and applying the result only after explicit confirmation.

Applying an Approved Expansion

import {
  createManagedExecutionBoundary,
  applySandboxBoundaryExpansion,
} from '@maka/runtime';

const approvedProfile = applySandboxBoundaryExpansion(
  currentBoundary.profile,
  expansion,
);
const newBoundary = createManagedExecutionBoundary(
  approvedProfile, 
  currentBoundary.revision + 1
);

Source: applySandboxBoundaryExpansion and createManagedExecutionBoundary in sandbox-boundary.ts, lines 84-46

Note the revision increment: every boundary state is versioned, creating an immutable audit trail.

Key Design Principles

The sandbox boundary language achieves three architectural goals:

1. Fail-closed safety — Missing or denied boundaries cause immediate runtime failure, never silent bypass
2. Platform neutrality — Same permissions compile to Seatbelt, bubblewrap, or AppContainer policies without semantic drift
3. Durable decisions — Requests and responses persist through crashes via the storage layer

As documented in packages/runtime/src/sandbox/README.md:

"The session ExecutionBoundary is the authority for whether an operation is currently inside the sandbox boundary. Sandbox selection does not expand that boundary."

Critical Source Files

File	Responsibility
packages/core/src/sandbox-boundary.ts	Type definitions, validation, expansion helpers
packages/runtime/src/sandbox/README.md	Runtime authority and backend selection
packages/runtime/src/sandbox/sandbox-manager.ts	Boundary selection and command transformation
packages/runtime/src/sandbox-boundary-tool.ts	User request flow and settlement
packages/runtime/src/sandbox-boundary-declaration.ts	Interaction message definitions
docs/architecture/windows-sandbox-rfc-v1.md	Platform-specific translation reference

Summary

• The sandbox boundary language provides a formal, versioned, cross-platform permission model for Maka sessions
• Three roles—permission description, runtime enforcement, and user-approved expansion—are cleanly separated in the codebase
• Immutable data structures in packages/core/src/sandbox-boundary.ts ensure auditability and crash recovery
• ExecutionBoundary types (managed/bypass/external) map neutral permissions to OS-specific backends without changing semantics
• User approval is mandatory: SandboxBoundaryRequest objects persist, display, and apply only after explicit consent

Frequently Asked Questions

What happens if a tool requests access outside its current boundary?

The operation is blocked by SandboxManager before execution. The tool may trigger a sandbox_boundary_required interaction (defined in packages/runtime/src/sandbox-boundary-declaration.ts), which pauses the turn and presents a request to the user. No automatic expansion occurs.

How does Maka prevent tampering with boundary state?

All boundary objects are immutable (readonly in TypeScript) and versioned. The revision field increments with every change, and the storage layer persists requests and responses durably. A crash or restart reconstructs the exact boundary state from this audit log.

Can the same boundary language work across all supported platforms?

Yes. The core types in packages/core/src/sandbox-boundary.ts are platform-neutral. Platform-specific code in packages/runtime/src/sandbox/ translates ExecutionBoundary profiles into Seatbelt profiles (macOS), bubblewrap arguments (Linux), or AppContainer configurations (Windows) without redefining permission semantics.

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