# How the Permission Profile System Enables Sandboxed Tool Execution in Apache Maka

> Discover how Apache Maka’s permission profile system secures tool execution. It defines file paths, network access, and sandbox types, compiling them into OS-specific configurations for isolated environments.

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

---

**Apache Maka isolates user-supplied tools by binding each execution to a declarative permission profile that specifies allowed file-system paths, network endpoints, and sandbox type, which the runtime compiles into OS-specific sandbox configurations.**

Apache Maka is an open-source framework designed to run AI plugins and utilities inside isolated environments. The **permission profile system** provides the declarative foundation for **sandboxed tool execution** by describing exactly what resources a tool may access before it starts. By transforming these high-level profiles into concrete OS-level restrictions, Maka ensures every tool operates with the minimum privileges necessary to prevent accidental or malicious side effects.

## Defining the Permission Profile Schema

The core schema for sandbox permissions lives in [[`packages/core/src/permission-profile.ts`](https://github.com/apache/maka/blob/main/packages/core/src/permission-profile.ts)](https://github.com/apache/maka/blob/main/packages/core/src/permission-profile.ts). This module defines the **`PermissionProfile`** type and enumerates three canonical sandbox kinds:

- **Managed** – A sandbox that the Maka runtime creates and controls directly.
- **Disabled** – A restrictive profile that blocks all external interaction, suitable for pure computation tools.
- **External** – A profile that delegates enforcement to an external sandbox implementation such as macOS Seatbelt.

The file also exports the **`FileSystemSandboxEntry`** type and a network policy structure. Together, these express granular allow/deny rules for specific file paths and network hosts, forming the complete declarative contract for tool execution.

## Maintaining Backward Compatibility with the Compiler

Because earlier product modes stored permission data in legacy formats, Maka provides a compilation layer in [[`packages/core/src/permission-profile-compiler.ts`](https://github.com/apache/maka/blob/main/packages/core/src/permission-profile-compiler.ts)](https://github.com/apache/maka/blob/main/packages/core/src/permission-profile-compiler.ts). The **`compilePermissionProfile`** function translates legacy descriptors into the current `PermissionProfile` shape. This step guarantees backward compatibility while keeping the sandbox enforcement logic consistent across all execution paths.

## Generating OS-Specific Sandboxes from Profiles

Runtime code reads a tool’s profile and materializes a sandbox appropriate for the host OS. Each platform-specific module imports `PermissionProfile` via `import type { PermissionProfile } from '@maka/core/permission-profile'` and uses the **`compilePermissionProfile`** helper to obtain a fully-validated profile before feeding it to the OS-specific builder:

- **Windows** – [[`packages/runtime/src/sandbox/windows-profile.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/windows-profile.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/windows-profile.ts) builds a *Windows Sandbox* manifest from the profile.
- **macOS** – [[`packages/runtime/src/sandbox/macos-seatbelt.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/macos-seatbelt.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/macos-seatbelt.ts) generates a Seatbelt profile.
- **Linux** – [[`packages/runtime/src/sandbox/linux-sandbox.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/linux-sandbox.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/linux-sandbox.ts) creates a *bubblewrap* sandbox.

This architecture allows the same declarative profile to enforce radically different underlying isolation technologies without changing the tool’s configuration.

## Runtime Enforcement and Profile Verification

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)](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/sandbox-manager.ts) receives the compiled profile and creates an **`ExecutionBoundary`**. When a tool launches, the manager passes this boundary to the runtime host in [[`packages/runtime-host/src/server/workspace-execution-composition.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/workspace-execution-composition.ts)](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/workspace-execution-composition.ts), which spawns the tool inside the sandbox.

To prevent privilege escalation, the boundary contains a unique **profile digest**—a SHA-256 hash of the serialized profile. The system persists this digest in the SQLite session store at [[`packages/storage/src/sqlite-session-metadata-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/sqlite-session-metadata-store.ts)](https://github.com/apache/maka/blob/main/packages/storage/src/sqlite-session-metadata-store.ts). Subsequent runs verify that the same profile is being reused, ensuring that a tool cannot silently gain additional permissions between executions.

## Using Factory Helpers for Common Profiles

Most code that needs a sandbox calls one of the factory helpers exported from the core module rather than constructing profiles manually:

- **`createReadOnlyPermissionProfile()`** – Produces a profile that permits only read-only file access.
- **`createWorkspaceWritePermissionProfile()`** – Creates a profile that allows the tool to write inside the current workspace’s sandboxed directory.

These factories appear throughout the test suite (e.g., [[`packages/runtime/src/__tests__/windows-sandbox.test.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/__tests__/windows-sandbox.test.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/__tests__/windows-sandbox.test.ts)) and in production code such as the built-in tool registry in [[`packages/runtime/src/builtin-tools.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts).

The following examples demonstrate how to execute tools with these pre-defined profiles:

```ts
// Example: grant a tool read-only access to the workspace
import { createReadOnlyPermissionProfile } from '@maka/core/permission-profile';

const profile = createReadOnlyPermissionProfile();
await runtimeHost.runTool('my-plugin', { profile });

```

```ts
// Example: grant a tool write access to a temporary sandbox directory
import { createWorkspaceWritePermissionProfile } from '@maka/core/permission-profile';

const profile = createWorkspaceWritePermissionProfile();
await runtimeHost.runTool('code-formatter', { profile });

```

## Summary

- The **permission profile system** in Apache Maka uses declarative `PermissionProfile` objects to specify exactly what resources a tool can access.
- The **compiler layer** in [`permission-profile-compiler.ts`](https://github.com/apache/maka/blob/main/permission-profile-compiler.ts) ensures legacy permission formats migrate seamlessly to the current schema.
- **OS-specific generators** translate profiles into native sandbox configurations: Windows Sandbox, macOS Seatbelt, and Linux bubblewrap.
- **Runtime enforcement** creates an `ExecutionBoundary` from the compiled profile and verifies integrity using a SHA-256 digest stored in SQLite.
- **Factory helpers** like `createReadOnlyPermissionProfile()` provide convenient, secure defaults for common use cases.

## Frequently Asked Questions

### What is a permission profile in Apache Maka?

A permission profile is a declarative data structure defined in [`packages/core/src/permission-profile.ts`](https://github.com/apache/maka/blob/main/packages/core/src/permission-profile.ts) that enumerates the specific resources—file-system paths, network endpoints, and sandbox type—that a tool is allowed to access. It serves as the single source of truth for sandbox configuration, enabling the runtime to enforce least-privilege execution regardless of the underlying operating system.

### How does Maka handle legacy permission configurations?

Maka addresses legacy formats through the **permission-profile-compiler** module in [`packages/core/src/permission-profile-compiler.ts`](https://github.com/apache/maka/blob/main/packages/core/src/permission-profile-compiler.ts). The `compilePermissionProfile` function transforms outdated permission descriptors into the modern `PermissionProfile` shape, ensuring backward compatibility while maintaining consistent sandbox enforcement logic across the entire framework.

### What sandbox technologies does Maka use on different operating systems?

According to the source code in `packages/runtime/src/sandbox/`, Maka maps profiles to three distinct technologies: Windows Sandbox manifests on Windows, Seatbelt profiles on macOS via [`macos-seatbelt.ts`](https://github.com/apache/maka/blob/main/macos-seatbelt.ts), and bubblewrap sandboxes on Linux via [`linux-sandbox.ts`](https://github.com/apache/maka/blob/main/linux-sandbox.ts). Each implementation consumes the same `PermissionProfile` interface but generates host-specific restriction rules.

### How does Maka prevent privilege escalation between tool runs?

The sandbox manager generates a SHA-256 **profile digest** from the serialized permission profile and stores it in the SQLite session metadata store at [`packages/storage/src/sqlite-session-metadata-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/sqlite-session-metadata-store.ts). When a tool restarts, the runtime verifies that the current profile hash matches the stored digest, ensuring that a tool cannot execute with a modified, more permissive profile than the one originally authorized.