Execution Boundary Contract for Sandbox Isolation in Apache Maka

The Apache Maka execution boundary contract requires every tool to declare a SandboxBoundary object listing required resources (file paths, network permissions, process limits), which the runtime validates and enforces through OS-level isolation before and during execution.

Apache Maka enforces sandbox isolation through a strict execution boundary contract that governs how tools access system resources. This contract ensures that every tool operates within predefined limits, protecting the host environment from unauthorized file access, network activity, or process manipulation. The implementation spans the runtime and core packages of the apache/maka repository.

Core Concepts of the Execution Boundary Contract

The execution boundary contract rests on three interlocking components that together guarantee isolation.

Sandbox-Boundary Declaration

Every tool invocation begins with a declarative contract. The caller constructs a SandboxBoundary object that explicitly lists:

• Read-only paths — directories and files the tool may read
• Write-only paths — locations where the tool may write output
• Network permissions — such as allowOutbound: true or false
• Process limits — CPU and memory caps

The declaration API lives in packages/runtime/src/sandbox-boundary-declaration.ts. This file exports the declareSandbox() helper and the SandboxBoundary type interface.

Sandbox-Boundary Enforcement

The runtime transforms declarations into OS-level isolation boundaries. In packages/core/src/sandbox-boundary.ts, the enforcement layer maps the declared capabilities to platform-specific mechanisms:

Platform	Isolation Mechanism
Windows	AppContainer via maka-windows-sandbox.exe
Linux	PID, mount, network, and user namespaces
macOS	Sandbox profiles with namespace isolation

The sandboxed process receives only the environment variables and file system mounts declared in its contract. Any attempt to access undeclared resources results in immediate termination.

Sandbox Manager and Recovery

The SandboxManager class in packages/runtime/src/sandbox/sandbox-manager.ts orchestrates sandbox lifecycles. It performs three critical functions:

1. Tracks active sandboxes and persists their contracts
2. Validates runtime behavior by comparing syscall logs against declarations
3. Recovers from host crashes by reconstructing sandboxes from persisted contracts

How the Execution Boundary Contract Works

Step 1: Declaration and Validation

Before launch, the runtime validates the SandboxBoundary against a whitelist of permitted capabilities. The validation logic in packages/runtime/src/sandbox-boundary-tool.ts rejects any declaration requesting unauthorized privileges—such as process.exec without explicit approval.

Step 2: Isolation and Launch

The sandbox manager spawns the tool inside the appropriate OS container:

# Pseudocode illustrating the launch flow in sandbox-manager.ts

if platform == 'win32':
    spawn('maka-windows-sandbox.exe', ['--profile', boundary_json])
elif platform == 'linux':
    unshare(CLONE_NEWNS | CLONE_NEWPID | CLONE_NEWNET | CLONE_NEWUSER)
    mount(boundary mounts)
    exec(tool_binary)

Step 3: Runtime Monitoring

During execution, the manager logs syscalls and file accesses. After completion, it compares observed behavior against the declared contract. Discrepancies trigger a SANDBOX_BOUNDARY_VIOLATION error, and the sandbox is destroyed.

Step 4: Recovery on Host Failure

If the Runtime Host crashes, the sandbox manager reconstructs the session from the persisted contract. The test file sandbox-boundary-restart-recovery.test.ts demonstrates this recovery flow, ensuring isolation guarantees survive process restarts.

Code Examples for Declaring and Enforcing Boundaries

Declaring a Sandbox Boundary for Tool Execution

import { SandboxBoundary, declareSandbox } from '@maka/runtime';

// Request read-only access to a project folder and write access to a temporary dir
const boundary: SandboxBoundary = declareSandbox({
  readOnly: ['/home/user/project'],
  writeOnly: ['/tmp/maka-sandbox'],
  network: { outbound: false },
});

await runtime.runTool('myTool', { sandboxBoundary: boundary });

This example from packages/runtime/src/sandbox-boundary-tool.ts shows the standard pattern: construct a boundary, then pass it to the runtime's tool execution method.

Direct Sandbox Manager Usage

import { SandboxManager } from '@maka/runtime/sandbox';

const manager = new SandboxManager([
  {
    clientPath: '/usr/local/bin/maka-linux-sandbox',
    program: '/usr/local/bin/maka-linux-sandbox',
    args: ['--profile', JSON.stringify(boundary)],
  },
]);

await manager.launch();

The SandboxManager constructor accepts an array of sandbox configurations and exposes launch() to start isolated execution. See packages/runtime/src/sandbox/sandbox-manager.ts for the full API surface.

Handling Boundary Violations

try {
  await runtime.runTool('dangerousTool', { sandboxBoundary: boundary });
} catch (e) {
  if (e.code === 'SANDBOX_BOUNDARY_VIOLATION') {
    console.error('Tool attempted an illegal operation:', e.details);
    // e.details contains the specific resource access that violated the contract
  }
}

The error handling pattern above, demonstrated in sandbox-boundary-restart-recovery.test.ts, allows calling code to distinguish contract violations from other runtime failures.

Key Source Files in the Execution Boundary Implementation

File	Module	Purpose
packages/runtime/src/sandbox-boundary-declaration.ts	Runtime	Type definitions and declareSandbox() factory
packages/runtime/src/sandbox-boundary-tool.ts	Runtime	Validation and launch orchestration
packages/runtime/src/sandbox/sandbox-manager.ts	Runtime	Lifecycle management, monitoring, and recovery
packages/core/src/sandbox-boundary.ts	Core	OS-specific isolation implementation
sandbox-boundary-restart-recovery.test.ts	Tests	Recovery and violation handling test coverage

Summary

• Apache Maka's execution boundary contract requires explicit resource declarations through SandboxBoundary objects before any tool runs.
• Validation occurs twice: at declaration time against capability whitelists, and at runtime by logging and comparing actual system access.
• OS-level isolation uses Windows AppContainers on Windows and namespace-based containers on Linux and macOS, all configured from the same declarative contract.
• The SandboxManager persists contracts, enables crash recovery, and enforces termination on boundary violations.
• All components are open-source in the apache/maka repository, with clear separation between declaration APIs (packages/runtime) and enforcement implementations (packages/core).

Frequently Asked Questions

What happens if a tool tries to access a file outside its declared sandbox boundary?

The sandboxed process receives an access denial from the OS-level isolation mechanism, and the SandboxManager logs the violation. After the tool exits, the manager compares the access attempt against the declared contract and throws a SANDBOX_BOUNDARY_VIOLATION error. The calling code can catch this error and inspect e.details for the specific violation.

How does the execution boundary contract persist across host process crashes?

The SandboxManager persists each sandbox's contract to durable storage before launching. If the Runtime Host crashes, the manager reconstructs the sandbox from this persisted state and re-applies the original isolation guarantees. The recovery flow is tested in sandbox-boundary-restart-recovery.test.ts.

Can a sandbox declaration request arbitrary system capabilities?

No. The validation logic in sandbox-boundary-tool.ts checks declarations against a whitelist of permitted capabilities. Requests for dangerous privileges—such as unrestricted process.exec—are rejected at the validation stage, before any OS container is created.

What platforms support the Apache Maka execution boundary contract?

The contract is fully supported on Windows (via AppContainer), Linux (via PID, mount, network, and user namespaces), and macOS (via sandbox profiles with namespace isolation). The packages/core/src/sandbox-boundary.ts file contains the platform-specific implementations selected at runtime based on process.platform.

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