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

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.

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

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

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

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 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, 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 renders this failure as a "sandbox blocked" status message, immediately notifying users that the attempted operation fell outside the session's declared sandbox boundary.

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