PermissionProfileCompiler in Apache Maka: How It Compiles Permission Profiles for Secure Execution

The PermissionProfileCompiler transforms a permission mode (explore, ask, or bypass) and working directory into a fully-qualified PermissionProfile that the runtime enforces during tool execution.

In Apache Maka, the PermissionProfileCompiler serves as the bridge between high-level user preferences and concrete sandbox security policies. Located in packages/core/src/permission-profile-compiler.ts, this core component ensures that every tool invocation runs with precisely defined filesystem and network permissions.

What PermissionProfileCompiler Does

The compiler's primary export, compilePermissionProfile, executes a four-step pipeline to derive sandbox configurations from simple mode strings.

Step 1: Collect Workspace Roots

The compiler first determines which directories constitute the trusted workspace. It uses explicitly provided workspaceRoots or falls back to the current working directory (cwd):

const workspaceRoots = input.workspaceRoots ?? [input.cwd];

Step 2: Select a Base Profile

Based on the requested mode, the compiler selects one of three built-in managed profiles:

Mode	Profile Selected	Permission Level
explore	read-only	Read access to workspace only
ask	workspace-write	Read/write to workspace, tmp directories
bypass	danger-full-access	Unrestricted filesystem and network access

This selection occurs via a switch (input.mode) statement in the compiler source.

Step 3: Wrap via compileManaged

The chosen profile passes through compileManaged, which attaches metadata including the standardized profileName and bundles the network sandbox policy.

return compileManaged(input.mode, /* ... */, workspaceRoots);

Step 4: Return CompiledDescription

The final CompiledPermissionProfile object contains:

• mode: The original permission mode
• profileName: Human-readable identifier (read-only, workspace-write, danger-full-access)
• profile: The full PermissionProfile with filesystem entries
• workspaceRoots: Normalized list of trusted paths
• network: Network policy configuration (restricted or enabled)

Where PermissionProfileCompiler Is Used

According to the Apache Maka source code, two primary systems consume the compiler's output.

Built-in Tool Runtime

In packages/runtime/src/builtin-tools.ts (lines 33-37), the runtime obtains a profile when a tool lacks an explicit profile definition. The compiler derives the effective security context from the session's permissionMode.

Filesystem Worker Client

In packages/runtime/src/filesystem-worker/client.ts (lines 296-301), each remote request triggers profile compilation to enforce filesystem permissions on the worker side. This ensures that even distributed operations respect the originating session's constraints.

Practical Usage Examples

Read-Only Exploration Mode

import { compilePermissionProfile } from '@maka/core/permission-profile-compiler';

const compiled = compilePermissionProfile({
  mode: 'explore',
  cwd: '/home/user/project',
});
// compiled.profileName === 'read-only'
// compiled.network.kind === 'restricted'

Workspace Write Mode with Multiple Roots

const compiled = compilePermissionProfile({
  mode: 'ask',
  cwd: '/home/user/project',
  workspaceRoots: ['/home/user/project', '/home/user/other'],
});
// compiled.profileName === 'workspace-write'
// Profile grants write access to :workspace_roots, :tmpdir, :slash_tmp

Bypass Mode (Full Access)

const compiled = compilePermissionProfile({
  mode: 'bypass',
  cwd: '/home/user/project',
});
// compiled.profileName === 'danger-full-access'
// compiled.profile.fileSystem.kind === 'unrestricted'
// compiled.network.kind === 'enabled'

Feeding Profiles to SandboxManager

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

const { profile, workspaceRoots } = compilePermissionProfile({
  mode: 'ask',
  cwd: '/repo',
});

SandboxManager.createSandbox({ profile, workspaceRoots });

Key Source Files

File	Purpose
packages/core/src/permission-profile-compiler.ts	Core compilePermissionProfile implementation
packages/core/src/permission-profile.ts	Profile definitions and helper creators
packages/runtime/src/builtin-tools.ts	Runtime usage for built-in tools
packages/runtime/src/filesystem-worker/client.ts	Remote filesystem enforcement
packages/runtime/src/sandbox/*	Platform-specific sandbox implementations (macOS Seatbelt, Linux seccomp)

Summary

• PermissionProfileCompiler converts permission modes into enforceable sandbox policies through compilePermissionProfile.
• Three modes map to three profiles: explore → read-only, ask → workspace-write, bypass → danger-full-access.
• The compiler normalizes workspace roots and bundles network policies into a CompiledPermissionProfile structure.
• Runtime systems in builtin-tools.ts and filesystem-worker/client.ts consume these profiles to enforce security boundaries.
• Platform-specific sandbox managers translate the abstract profile into concrete OS restrictions.

Frequently Asked Questions

What permission modes does PermissionProfileCompiler support?

The compiler supports three modes defined in the Apache Maka source: explore (read-only workspace access), ask (read/write to workspace and temporary directories), and bypass (unrestricted filesystem and network access). Each mode maps to a predefined managed profile with specific canReadPath and canWritePath entries.

How does PermissionProfileCompiler determine which directories are trusted?

The compiler checks input.workspaceRoots first; if undefined, it defaults to [input.cwd]. This logic appears in packages/core/src/permission-profile-compiler.ts. Callers can explicitly pass multiple roots to extend the trusted boundary beyond the current working directory.

Can I use PermissionProfileCompiler directly in my own tools?

Yes. Import compilePermissionProfile from @maka/core/permission-profile-compiler and pass a configuration object with mode and cwd. The function returns a CompiledPermissionProfile suitable for SandboxManager.createSandbox() or custom enforcement logic.

What happens to the network policy in each mode?

The compiler sets network.kind to restricted for explore and ask modes, blocking external connections. Only bypass mode yields network.kind === 'enabled'. This policy is bundled by compileManaged and enforced by platform-specific sandbox implementations in packages/runtime/src/sandbox/.

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