# What Is the Sandbox Boundary in Apache Maka and How Is Tool Access Approved?

> Understand the Apache Maka sandbox boundary for secure tool execution. Learn how manifest validation approves tool access against an explicit capability allowlist.

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

---

**The sandbox boundary in Apache Maka is a security contract that isolates tool execution from the host runtime, enforced via platform-specific sandboxes like Windows AppContainer and macOS sandbox profiles, with access approved only after manifest validation against an explicit capability allowlist.**

Apache Maka is an open-source framework for building conversational AI applications where external tools execute in isolated environments. The **sandbox boundary** serves as the critical security gate that separates untrusted tool code from the host application, ensuring that every tool operates within strictly defined resource limits. This architectural boundary is defined in the core package and enforced across all supported platforms through a combination of static validation and OS-level isolation.

## Understanding the Sandbox Boundary Architecture

The sandbox boundary is not merely a configuration file but a comprehensive enforcement layer that mediates all interactions between the host application and invoked tools.

### The Core Contract in sandbox-boundary.ts

At the heart of the system lies the boundary definition located in [[`packages/core/src/sandbox-boundary.ts`](https://github.com/apache/maka/blob/main/packages/core/src/sandbox-boundary.ts)](https://github.com/apache/maka/blob/main/packages/core/src/sandbox-boundary.ts). This file declares the **capability allowlist**—a strict enumeration of permissible operations including filesystem paths, network endpoints, and environment variables. The boundary object validates every incoming tool manifest against this contract before execution begins, rejecting any request that falls outside the predefined limits.

### Platform-Specific Enforcement Mechanisms

While the boundary defines the rules, platform-specific implementations enforce them at the kernel level. On Windows, the system leverages **AppContainer** isolation with restricted capability SIDs and job object markers; on macOS, it applies **sandbox profiles**; Linux implementations utilize namespace segregation. The orchestration of these protections is handled by the runtime's sandbox manager.

## How Tool Access Is Approved

Tool access follows a rigorous approval workflow that inspects capabilities before granting runtime privileges.

### Manifest Declaration and Validation

Every tool must ship with a JSON **manifest** specifying required capabilities such as `readFile`, `networkAccess`, or `envVar` access. Before launch, the **Sandbox Manager**—implemented in [[`packages/runtime/src/sandbox/sandbox-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/sandbox-manager.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/sandbox-manager.ts)—parses this manifest and verifies each requested permission against the **Sandbox Boundary** definition. Only capabilities explicitly present in the boundary are granted; any deviation results in immediate rejection.

```typescript
// Example: Defining a sandbox boundary with allowed capabilities
import { SandboxBoundary } from '@maka/core/sandbox-boundary';

const boundary = new SandboxBoundary({
  allowRead: ['/usr/share/maka/tools'],
  allowNetwork: ['https://api.openai.com'],
  disallowEnv: ['SECRET_KEY'],
});

```

### Runtime Isolation and Launch

Once validated, the manager instantiates the platform-specific sandbox environment and launches the tool process. The tool runs with only the approved capabilities, and the operating system kernel enforces these constraints in real time. Attempts to access unapproved resources trigger immediate process termination. Continuous validation is maintained through end-to-end scripts such as [`scripts/verify-windows-sandbox-e2e.mjs`](https://github.com/apache/maka/blob/main/scripts/verify-windows-sandbox-e2e.mjs), which verifies that AppContainer flags and atomic-job markers are correctly applied.

```typescript
// Example: Launching a tool through the Sandbox Manager
import { SandboxManager } from '@maka/runtime/sandbox/sandbox-manager';
import { readFileSync } from 'fs';

const manifest = JSON.parse(readFileSync('my-tool/manifest.json', 'utf-8'));
const manager = new SandboxManager({ boundary });

await manager.launchTool(manifest); // throws if manifest violates the boundary

```

## Handling Security Violations and User Feedback

When a tool requests capabilities outside the approved boundary, the system must communicate the denial clearly without exposing internal details.

### The Denial UI Component

The presentation layer handles rejection through [[`packages/ui/src/tool-activity/sandbox-denial.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/tool-activity/sandbox-denial.ts)](https://github.com/apache/maka/blob/main/packages/ui/src/tool-activity/sandbox-denial.ts). This module renders user-facing error messages when capability validation fails, ensuring transparency about why a tool cannot execute specific operations.

```typescript
// Example: UI feedback when a tool is denied
import { showSandboxDenial } from '@maka/ui/tool-activity/sandbox-denial';

function handleToolRequest(request) {
  if (!boundary.isAllowed(request.capabilities)) {
    showSandboxDenial(request);
  }
}

```

## Summary

- The **sandbox boundary** is defined in [`packages/core/src/sandbox-boundary.ts`](https://github.com/apache/maka/blob/main/packages/core/src/sandbox-boundary.ts) and establishes the immutable capability contract for all tool executions.
- **Tool access approval** requires strict manifest validation against the boundary allowlist via the Sandbox Manager in [`packages/runtime/src/sandbox/sandbox-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/sandbox-manager.ts).
- Platform-specific sandboxes (Windows AppContainer, macOS profiles, Linux namespaces) enforce the boundary at the OS level, terminating processes that attempt unauthorized access.
- Violations are surfaced to users through the [`packages/ui/src/tool-activity/sandbox-denial.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/tool-activity/sandbox-denial.ts) UI component, providing clear security feedback.
- Automated verification scripts in `scripts/verify-windows-sandbox-e2e.mjs` continuously audit the enforcement mechanisms to ensure boundary integrity.

## Frequently Asked Questions

### What happens if a tool requests a capability not defined in the sandbox boundary?

The Sandbox Manager rejects the tool's manifest during the pre-launch validation phase, preventing the process from starting. If a tool attempts to bypass the manifest and access restricted resources at runtime, the OS-level sandbox (AppContainer, macOS sandbox, or Linux namespace) immediately terminates the process and logs the violation.

### How does Apache Maka enforce the sandbox boundary on Windows?

Maka utilizes Windows **AppContainer** isolation with restricted capability SIDs and job objects. The `scripts/verify-windows-sandbox-e2e.mjs` validation suite confirms that tool processes run inside the correct AppContainer with atomic-job markers, ensuring that the sandbox boundary is active from process creation through termination.

### Can developers modify the sandbox boundary to grant additional privileges?

No. The sandbox boundary is established by the host application administrator in [`packages/core/src/sandbox-boundary.ts`](https://github.com/apache/maka/blob/main/packages/core/src/sandbox-boundary.ts) and is immutable at runtime. Tool developers must declare required capabilities in their manifest and request approval; they cannot escalate privileges beyond the predefined boundary without modifying the core source code and redeploying the host application.

### Where is the user interface implemented for sandbox denial messages?

The denial interface is implemented in [`packages/ui/src/tool-activity/sandbox-denial.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/tool-activity/sandbox-denial.ts). This file exports the `showSandboxDenial` function and related UI components that render security warnings when a tool's requested capabilities fail validation against the sandbox boundary, ensuring users receive immediate, actionable feedback.