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

> Discover the sandbox boundary language in Apache Maka. Learn its purpose for defining session permissions and how it ensures runtime enforcement for secure expansions.

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

---

**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`](https://github.com/apache/maka/blob/main/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

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

```

Source: *[`packages/core/src/sandbox-boundary.ts`](https://github.com/apache/maka/blob/main/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

```ts
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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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

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

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

```

Source: *`sandboxBoundaryExpansionAllowsPath`, lines 70-81 of [`sandbox-boundary.ts`](https://github.com/apache/maka/blob/main/sandbox-boundary.ts)*

This function is consulted by `SandboxManager` in [`packages/runtime/src/sandbox/sandbox-manager.ts`](https://github.com/apache/maka/blob/main/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

```ts
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`](https://github.com/apache/maka/blob/main/packages/core/src/sandbox-boundary.ts)*

The [`sandbox-boundary-tool.ts`](https://github.com/apache/maka/blob/main/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

```ts
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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/core/src/sandbox-boundary.ts) | Type definitions, validation, expansion helpers |
| [`packages/runtime/src/sandbox/README.md`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/README.md) | Runtime authority and backend selection |
| [`packages/runtime/src/sandbox/sandbox-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/sandbox-manager.ts) | Boundary selection and command transformation |
| [`packages/runtime/src/sandbox-boundary-tool.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox-boundary-tool.ts) | User request flow and settlement |
| [`packages/runtime/src/sandbox-boundary-declaration.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox-boundary-declaration.ts) | Interaction message definitions |
| [`docs/architecture/windows-sandbox-rfc-v1.md`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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.