# How Maka Enforces Sandbox Boundaries for File‑Write and Shell‑Run Tools

> Understand Maka's sandbox boundary for file-write and shell-run tools. Learn how tools gain approval for execution scope expansion.

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

---

**A sandbox boundary in Apache Maka is a permission profile that controls filesystem, network, and execution scope, and tools pass approval checks by requesting boundary expansions that transition from `pending` to `approved` status before execution proceeds.**

Apache Maka isolates every tool invocation inside a **sandbox boundary** to prevent unauthorized access to host resources. This boundary acts as a mutable permission profile that governs what a specific session may access, requiring explicit approval before expanding its privileges. Understanding how file-write and shell-run tools interact with these boundaries is essential for building secure agentic workflows.

## What Is a Sandbox Boundary in Maka?

A **sandbox boundary** is the core isolation primitive defined in [`packages/core/src/sandbox-boundary.ts`](https://github.com/apache/maka/blob/main/packages/core/src/sandbox-boundary.ts). It functions as a declarative permission profile containing three primary components:

- **Filesystem** – An array of `SandboxBoundaryFilesystemEntry` objects, where each entry specifies a **path**, an **access** level (`read` or `write`), and a **scope** (`exact` for that specific path or `subtree` for nested directories).
- **Network** – A configuration flag (`enabled: true`) that controls outbound network traffic.
- **Kind** – The boundary classification: **managed** (mutable and expandable), **bypass** (full host privileges), or **external** (fully isolated).

When a tool requires access beyond its current boundary, it creates a **sandbox-boundary expansion** and submits a `SandboxBoundaryRequest`. This request initializes with a **`pending`** status and enters the approval pipeline for review.

## How File‑Write Tools Pass Sandbox Boundary Approval

File-write tools must navigate a three-stage validation process before modifying the filesystem. The implementation spans [`packages/runtime/src/file-write-lock.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/file-write-lock.ts) and [`packages/runtime/src/filesystem-executor.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/filesystem-executor.ts).

### Step 1: Serialize Concurrent Access with File Write Locks

To prevent race conditions, the tool first acquires a per-file lock using **`withFileWriteLock`**. This helper serializes all concurrent edits targeting the same absolute path.

```typescript
import { withFileWriteLock } from '@maka/runtime/file-write-lock';
import { execFile } from '@maka/runtime/filesystem-executor';

// Serialize edits to absPath; queue if another write is in progress
await withFileWriteLock(absPath, async () => {
  await execFile({ path: absPath, content: newContent });
});

```

### Step 2: Validate Against Current Execution Boundary

The filesystem executor internally calls **`sandboxBoundaryExpansionAllowsPath`** (exported from the core module) to verify whether the current managed boundary already grants `write` access to the target path.

```typescript
if (!sandboxBoundaryExpansionAllowsPath(permission, target, 'write')) {
  // Path not covered → escalate to approval request
}

```

### Step 3: Create and Await Approval Expansion

If the path lacks coverage, Maka invokes **`CreateSandboxBoundaryRequest`** to generate a pending request stored in the **Plan Store**. This request includes the required filesystem entry and justification. Upon approval, **`applySandboxBoundaryExpansion`** generates a new execution boundary that incorporates the write permission, allowing the tool to proceed.

A file-write tool passes the sandbox boundary check only when either (a) the active boundary already contains the necessary write entry, or (b) an approved expansion adds it dynamically.

## How Shell‑Run Tools Pass Sandbox Boundary Approval

Shell-run tools follow an identical boundary validation workflow but typically request broader permissions spanning both filesystem and network resources. The logic is orchestrated by [`packages/runtime/src/shell-run-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/shell-run-manager.ts).

### Building the Resource Request

The tool constructs a `ShellRunWriteInput` referencing a **`ShellRunResourceRef`**, specifying the working directory, command, and environmental requirements.

### Dual Permission Validation

The **Shell‑Run Manager** validates the request against two criteria:

1. **Filesystem access** – Calls `sandboxBoundaryExpansionAllowsPath` for any file paths (e.g., temporary directories).
2. **Network access** – Checks `permission.network.kind === 'enabled'`.

```typescript
if (!sandboxBoundaryExpansionAllowsPath(boundary, '/tmp/maka-shell', 'write') ||
    !boundary.network?.enabled) {
  // Queue SandboxBoundaryRequest with filesystem + network expansion
}

```

### Approval-Gated Execution

If either permission is missing, Maka creates a `SandboxBoundaryRequest` containing the required filesystem entries and `network: { enabled: true }`. The shell-run controller cannot touch the host OS until the boundary expands. Notably, the model sees only the **approval summary** (human-readable justification and `approvalClass`), ensuring it cannot circumvent the sandbox constraints.

## The Sandbox Boundary Approval Flow

The complete lifecycle from tool invocation to execution follows these stages:

1. **Tool requests expansion** – The tool identifies required filesystem entries and/or network access beyond its current boundary.
2. **Runtime validation** – The executor calls `sandboxBoundaryExpansionAllowsPath` and inspects the network flag.
3. **Pending request creation** – If uncovered, Maka creates a `SandboxBoundaryRequest` with status `pending` and persists it to the Plan Store.
4. **User or policy approval** – A human reviewer or automated policy evaluates the request; upon approval, the status becomes `approved`.
5. **Boundary expansion** – Maka calls `applySandboxBoundaryExpansion` to produce a new managed execution boundary, stores it, and resumes the tool.

## Summary

- A **sandbox boundary** is a permission profile defined in [`sandbox-boundary.ts`](https://github.com/apache/maka/blob/main/sandbox-boundary.ts) that controls filesystem paths, network access, and execution kind.
- **File-write tools** use `withFileWriteLock` for serialization and `sandboxBoundaryExpansionAllowsPath` for validation, creating a `SandboxBoundaryRequest` when write access is not yet granted.
- **Shell-run tools** validate both filesystem paths and network permissions, queuing expansion requests that must include `network: { enabled: true }` for outbound connectivity.
- All expansion requests start as `pending` and require explicit approval via `applySandboxBoundaryExpansion` before the tool executes.
- The **Shell‑Run Manager** and **filesystem executor** enforce that no host resource is accessed until the boundary officially expands.

## Frequently Asked Questions

### What happens when a tool requests access outside its current sandbox boundary?

When a tool targets a path or resource outside its existing boundary, the runtime calls `sandboxBoundaryExpansionAllowsPath` to check coverage. If the check fails, Maka automatically creates a `SandboxBoundaryRequest` with status `pending` and stores it in the Plan Store. The tool pauses execution until a user or automated policy approves the expansion, at which point `applySandboxBoundaryExpansion` updates the boundary and resumes the operation.

### How does Maka prevent race conditions during concurrent file writes?

Maka prevents race conditions through the **`withFileWriteLock`** helper in [`packages/runtime/src/file-write-lock.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/file-write-lock.ts). This function serializes access to specific file paths, ensuring that only one write operation executes at a time per absolute path. Subsequent calls queue asynchronously until the active lock releases.

### Can automated policies approve sandbox boundary requests without human intervention?

Yes. While the analysis mentions that requests are routed through an approval pipeline where "the user (or an automated policy) reviews the request," the core mechanism supports automated approval. Once an automated policy grants approval, the request status transitions from `pending` to `approved`, triggering `applySandboxBoundaryExpansion` exactly as it would for manual review.

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

The **Kind** property defines three boundary types: **Managed** boundaries are mutable permission profiles that can expand via approved `SandboxBoundaryRequest` objects; **Bypass** boundaries grant full host privileges without restrictions; and **External** boundaries enforce complete isolation from the host environment. Production deployments typically use managed boundaries to maintain strict access control while allowing necessary expansions.