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

> Understand the Maka ExecutionBoundary, its security model, and how it controls filesystem and network permissions for sessions and tools. Learn about its typed object variants.

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

---

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

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

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

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

```ts
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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool-runtime.ts) | Consumes `ExecutionBoundary` to select sandbox profiles for individual tools. |
| [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts) | Uses `executionBoundaryContains` for session-level permission hierarchy. |
| [`packages/runtime-host/src/server/workspace-execution-composition.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/core/src/sandbox-boundary.ts) in the `@maka/core` package.