# What Is the Sandbox Boundary in Apache Maka and How Does It Enforce Security

> Understand the Apache Maka sandbox boundary. Learn how this declarative permission profile secures user sessions by isolating filesystem and network access through validation and kernel interception.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: security-guide
- Published: 2026-08-28

---

**The Apache Maka sandbox boundary is a declarative permission profile that isolates each user session by explicitly defining accessible filesystem paths and network capabilities, enforced through validation, containment checks, and runtime kernel interception.**

Apache Maka implements defense-in-depth through a strict sandbox boundary that governs every tool execution. This boundary acts as a security contract between the user session and the host system, ensuring operations remain confined to explicitly permitted resources. Understanding how Maka defines, validates, and enforces these boundaries is essential for securing AI-assisted development workflows.

## Declaring the Sandbox Boundary

Every session begins with a boundary declaration stored in the session metadata table (`sandbox_boundary_log`). A sandbox-boundary request contains an **expansion**—a structured payload enumerating filesystem entries and an optional network-enable flag. These declarations create an immutable audit trail tracking exactly what resources the session requested and when.

### Genesis Execution Boundaries

Maka initializes sessions with a genesis boundary created via `createGenesisExecutionBoundary`. Developers choose between **"explore"** (read-only workspace access) or **"bypass"** (unrestricted access), establishing the initial security posture before any expansion occurs.

```typescript
import { createGenesisExecutionBoundary } from '@maka/core/sandbox-boundary';

// "explore" gives read-only workspace access; "bypass" gives unrestricted access.
const boundary = createGenesisExecutionBoundary('explore');

```

## Validation Rules and Constraints

Before any expansion applies, `validateSandboxBoundaryExpansion` in [`packages/core/src/sandbox-boundary.ts`](https://github.com/apache/maka/blob/main/packages/core/src/sandbox-boundary.ts) enforces hard limits that prevent boundary abuse:

- **Path Normalization**: Every entry must resolve to a normalized absolute path
- **Entry Limit**: Maximum 32 filesystem entries per request
- **Size Limit**: Serialized payload cannot exceed 64 KB
- **Deny Rule Conflict**: No entry may contradict an existing explicit deny rule

```typescript
import { validateSandboxBoundaryExpansion } from '@maka/core/sandbox-boundary';

const raw = {
  filesystem: {
    entries: [
      { path: '/home/user/project', access: 'write', scope: 'subtree' },
      { path: '/tmp', access: 'read', scope: 'exact' },
    ],
  },
  network: { enabled: true },
};

const result = validateSandboxBoundaryExpansion(raw);
if (!result.ok) {
  console.error('Invalid expansion:', result.reason, result.message);
} else {
  console.log('Valid expansion:', result.expansion);
}

```

## Containment Checking During Execution

During tool execution, the runtime determines whether the current execution boundary permits an operation through `executionBoundaryContains`, also defined in [`sandbox-boundary.ts`](https://github.com/apache/maka/blob/main/sandbox-boundary.ts). Maka distinguishes three boundary types that affect containment logic:

- **Bypass boundaries** always contain the request, granting unrestricted system access
- **External boundaries** only contain other external boundaries, creating strict isolation layers
- **Managed boundaries** compare underlying permission profiles to determine if the requested operation falls within the declared sandbox

## Applying and Persisting Permissions

Once validated, `applySandboxBoundaryExpansion` merges new permissions into the existing `SandboxProfile`, producing a new managed execution boundary with an incremented revision number. This immutable approach ensures that permission changes are atomic and traceable.

```typescript
import {
  createManagedExecutionBoundary,
  applySandboxBoundaryExpansion,
} from '@maka/core/sandbox-boundary';
import { createWorkspaceWritePermissionProfile } from '@maka/core/permission-profile';

// Existing managed boundary
const baseProfile = createWorkspaceWritePermissionProfile();
const baseBoundary = createManagedExecutionBoundary(baseProfile, 0);

// Expansion obtained from a sandbox-boundary request
const { expansion } = result; // from the previous example

// Produce the new profile and boundary
const newProfile = applySandboxBoundaryExpansion(baseProfile, expansion);
const newBoundary = createManagedExecutionBoundary(newProfile, baseBoundary.revision + 1);

```

### Crash-Resilient Persistence

The [`sqlite-session-metadata-store.ts`](https://github.com/apache/maka/blob/main/sqlite-session-metadata-store.ts) module persists every sandbox-boundary request and its decision (allow/deny) to SQLite. On host restart, any pending requests not yet marked as allowed automatically receive a `host_restarted` denial closure, ensuring that transient permission grants never survive system crashes.

## Runtime Enforcement Layer

All filesystem and network calls traverse the **filesystem-worker** and **runtime-kernel** layers. Before execution, these layers invoke `sandboxBoundaryExpansionAllowsPath` (from [`sandbox-boundary.ts`](https://github.com/apache/maka/blob/main/sandbox-boundary.ts)) to verify path access permissions. Network operations check the enable flag established during boundary declaration. Violations trigger a `sandboxBoundaryFailure` that surfaces in the UI as a sandbox-blocked status via components in `packages/ui/src/tool-activity`.

```typescript
import { sandboxBoundaryExpansionAllowsPath } from '@maka/core/sandbox-boundary';

const allowed = sandboxBoundaryExpansionAllowsPath(
  expansion,
  '/home/user/project/src/app.ts',
  'write',
);
console.log('Write access allowed?', allowed);

```

When enforcement fails, the UI layer uses translation keys defined in [`packages/ui/src/tool-activity/copy.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/tool-activity/copy.ts) to render messages such as "Operation may have been blocked by sandbox," providing immediate feedback that the operation exceeded the session's declared permissions.

## Summary

- The sandbox boundary in Apache Maka is a declarative permission profile limiting session access to specific filesystem paths and network capabilities defined in an expansion payload.
- Validation occurs through `validateSandboxBoundaryExpansion`, enforcing 32-entry limits, 64KB payload maximums, absolute path normalization, and deny-rule conflicts.
- Three boundary types—**bypass**, **external**, and **managed**—determine containment via `executionBoundaryContains` based on the sensitivity of the execution context.
- Runtime enforcement happens in the filesystem-worker and runtime-kernel layers using `sandboxBoundaryExpansionAllowsPath` before any system call executes.
- SQLite persistence in `sandbox_boundary_log` ensures crash recovery by auto-denying pending requests with `host_restarted` status on system restart.
- UI components in `packages/ui/src/tool-activity` translate `sandboxBoundaryFailure` payloads into user-visible "sandbox blocked" diagnostics.

## Frequently Asked Questions

### What happens when a sandbox boundary request exceeds the 32-entry limit?

The `validateSandboxBoundaryExpansion` function returns a validation failure with reason `too_many_entries`, preventing the expansion from merging into the session profile. The user must reduce the number of requested paths and submit a new boundary request.

### How does Apache Maka handle sandbox permissions after a host restart?

According to the source code in [`sqlite-session-metadata-store.ts`](https://github.com/apache/maka/blob/main/sqlite-session-metadata-store.ts), the system persists all sandbox-boundary requests to SQLite. When the host restarts, any requests still pending a decision automatically receive a `host_restarted` denial closure, ensuring no stale permission grants survive the restart.

### What is the difference between bypass, external, and managed execution boundaries?

A **bypass** boundary unconditionally contains all operations, granting full system access without restriction. An **external** boundary creates strict isolation that only contains other external boundaries, blocking access to managed resources. A **managed** boundary enforces fine-grained permissions by comparing the requested path or capability against the underlying `SandboxProfile` permissions.

### Where are sandbox boundary violations displayed in the user interface?

When `sandboxBoundaryExpansionAllowsPath` denies an operation, the runtime generates a `sandboxBoundaryFailure` payload. The UI layer in [`packages/ui/src/tool-activity/copy.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/tool-activity/copy.ts) renders this failure as a "sandbox blocked" status message, immediately notifying users that the attempted operation fell outside the session's declared sandbox boundary.