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

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

// 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, which verifies that AppContainer flags and atomic-job markers are correctly applied.

// 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). This module renders user-facing error messages when capability validation fails, ensuring transparency about why a tool cannot execute specific operations.

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

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