# Execution Boundary Contract for Sandbox Isolation in Apache Maka

> Discover the Apache Maka execution boundary contract for sandbox isolation. Learn how it declares required resources and enforces OS-level security for safe tool execution.

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

---

**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](https://github.com/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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:

```python

# 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`](https://github.com/apache/maka/blob/main/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

```typescript
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`](https://github.com/apache/maka/blob/main/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

```typescript
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`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/sandbox-manager.ts) for the full API surface.

### Handling Boundary Violations

```typescript
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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox-boundary-declaration.ts) | Runtime | Type definitions and `declareSandbox()` factory |
| [`packages/runtime/src/sandbox-boundary-tool.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox-boundary-tool.ts) | Runtime | Validation and launch orchestration |
| [`packages/runtime/src/sandbox/sandbox-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/sandbox-manager.ts) | Runtime | Lifecycle management, monitoring, and recovery |
| [`packages/core/src/sandbox-boundary.ts`](https://github.com/apache/maka/blob/main/packages/core/src/sandbox-boundary.ts) | Core | OS-specific isolation implementation |
| [`sandbox-boundary-restart-recovery.test.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/sandbox-boundary-restart-recovery.test.ts).

### Can a sandbox declaration request arbitrary system capabilities?

No. The validation logic in [`sandbox-boundary-tool.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/core/src/sandbox-boundary.ts) file contains the platform-specific implementations selected at runtime based on `process.platform`.