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

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

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

// 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 });

// 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 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 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. 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, and bubblewrap sandboxes on Linux via 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. 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.

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