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

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

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.

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.

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

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

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