What Does the ExecutionBoundary Define in Maka? Understanding the Security Model

The ExecutionBoundary in Maka defines the core security model that determines what a session or tool is allowed to do, expressing authority over filesystem and network permissions through a typed object with three distinct variants.

The ExecutionBoundary sits at the heart of Maka's sandboxing architecture. Every running session operates within an execution boundary that gates all runtime actions—file reads, writes, network access, and future extensions. Higher-level components including the tool runtime, session manager, and runtime host all rely on this boundary to enforce security and present consistent permission information to users.

ExecutionBoundary Variants

Maka implements three distinct kinds of execution boundaries, each serving different trust scenarios.

Managed Boundaries

The managed variant carries a full sandbox permission profile (SandboxProfile) that describes allowed filesystem paths, access modes, and network enablement. This is the standard boundary for user-facing tools that need controlled access to the workspace.

import { createManagedExecutionBoundary, createWorkspaceWritePermissionProfile } from '@maka/core';

// Build a permission profile that allows reading and writing within the workspace
const profile = createWorkspaceWritePermissionProfile();

// Create the execution boundary with the profile and an initial revision
const boundary = createManagedExecutionBoundary(profile, 0);

Bypass Boundaries

The bypass variant is a lightweight boundary that grants unrestricted execution. Maka uses this for trusted internal operations where sandboxing would add unnecessary overhead.

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

// Bypass boundaries grant unrestricted execution; revision can be 0 for a fresh instance
const bypass = createBypassExecutionBoundary(0);

External Boundaries

The external variant represents an opaque boundary that does not expose a profile. Sessions running with this boundary are considered isolated from the host system.

Revision Tracking for Deterministic Caching

Every ExecutionBoundary carries a revision number that increments whenever the underlying profile changes. This design enables:

• Deterministic caching of permission decisions
• Conflict resolution when boundaries evolve during long-running sessions
• Equality comparisons without deep profile inspection

The revision pattern appears throughout packages/core/src/sandbox-boundary.ts where boundary factories accept an explicit revision parameter.

Permission Display Modes

The executionBoundaryDisplayMode() function translates an ExecutionBoundary into a user-visible permission mode. This mapping drives how the UI communicates sandbox status to users.

import { executionBoundaryDisplayMode } from '@maka/core';
import type { ExecutionBoundary } from '@maka/core';

function describeBoundary(boundary: ExecutionBoundary): string {
  const mode = executionBoundaryDisplayMode(boundary);
  switch (mode) {
    case 'explore': return 'Read‑only';
    case 'ask':     return 'Writable';
    case 'bypass':  return 'Bypass (unrestricted)';
    default:        return 'External/isolated';
  }
}

The four possible display modes are:

• explore – Read-only access
• ask – Writable permissions with user confirmation
• bypass – Unrestricted execution
• undefined – External or isolated boundary

Hierarchical Containment Checks

The executionBoundaryContains(parent, child) function verifies whether one boundary subsumes another. This containment logic supports expanding sandboxes and validating that tool requests stay within allowed scope.

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

const parent = createManagedExecutionBoundary(createReadOnlyPermissionProfile(), 1);
const child  = createManagedExecutionBoundary(createWorkspaceWritePermissionProfile(), 2);

if (executionBoundaryContains(parent, child)) {
  console.log('Child is allowed inside parent');
} else {
  console.log('Child exceeds parent permissions');
}

As implemented in packages/runtime/src/session-manager.ts, this containment check enforces hierarchical permission verification across sessions.

Key Implementation Files

File	Role
packages/core/src/sandbox-boundary.ts	Defines the ExecutionBoundary type, factory functions, display mode mapping, and containment logic (lines 62-75).
packages/runtime/src/tool-runtime.ts	Consumes ExecutionBoundary to select sandbox profiles for individual tools.
packages/runtime/src/session-manager.ts	Uses executionBoundaryContains for session-level permission hierarchy.
packages/runtime-host/src/server/workspace-execution-composition.ts	Constructs managed boundaries when workspaces initialize.

Summary

• The ExecutionBoundary is Maka's authoritative gate for all runtime security decisions.
• Three variants exist: managed (profile-based), bypass (unrestricted), and external (opaque/isolated).
• Revision tracking enables efficient caching and deterministic equality checks.
• executionBoundaryDisplayMode() maps boundaries to UI-friendly permission labels.
• executionBoundaryContains() enforces hierarchical permission scoping across sessions.

Frequently Asked Questions

What happens when an ExecutionBoundary revision changes?

When a boundary's revision increments, cached permission decisions become invalid. Maka's runtime host recomputes containment relationships and may trigger sandbox reconfiguration or session termination if the new boundary is more restrictive.

Can ExecutionBoundary kinds be mixed in containment checks?

Yes. The executionBoundaryContains function handles cross-kind comparisons according to rules in sandbox-boundary.ts. A bypass boundary contains any other boundary, while external boundaries are generally inscrutable and treated conservatively.

How does Maka choose between managed and bypass boundaries?

Maka selects managed boundaries for user-installed tools and workspace operations. It reserves bypass boundaries for internal system components that require full system access, such as the language server or extension host bootstrap.

Where is the ExecutionBoundary type defined?

The canonical type definition and all factory functions reside in packages/core/src/sandbox-boundary.ts in the @maka/core package.

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