How to Request a Sandbox Boundary in Apache Maka: A Complete Guide

In Apache Maka, you request a sandbox boundary by configuring an ExecutionBoundary profile (such as workspace-write) on a Session, which triggers the SandboxManager to generate platform-specific isolation commands after user approval via the sandbox-boundary-prompt UI component.

Apache Maka is an open-source runtime designed to execute AI-generated code safely by isolating potentially dangerous operations inside OS-level sandboxes. When you need to run tools that access the filesystem or network, you must request a sandbox boundary to ensure these actions remain contained within Seatbelt (macOS), Bubblewrap (Linux), or AppContainer (Windows) environments.

Understanding Sandbox Boundaries in Apache Maka

A sandbox boundary is the security mechanism that isolates tool actions inside an OS-level sandbox. According to the Apache Maka source code, this boundary prevents unauthorized filesystem writes and network calls by wrapping execution commands with platform-specific sandboxing technologies.

The boundary system revolves around the ExecutionBoundary class defined in packages/runtime/src/sandbox/types.ts. This object records the current sandbox policy for a session and determines whether subsequent tool calls require isolation.

How to Request a Sandbox Boundary Programmatically

You can request a sandbox boundary through three primary interfaces: the Session API, the built-in ask tool, or React UI hooks.

Using the Session API

The most direct method involves configuring a Session with an ExecutionBoundary profile that requires sandboxing.

import { Session } from '@maka/runtime';
import { ExecutionBoundary } from '@maka/runtime/src/sandbox/types';

// Obtain the current session from CLI or UI context
const session: Session = getActiveSession();

// Request sandbox boundary with workspace-write profile
await session.setExecutionBoundary(
  ExecutionBoundary.create({
    profile: 'workspace-write',
    require: true, // Fails if sandbox unavailable
  })
);

Setting require: true ensures the operation fails if the host system cannot provide sandbox isolation. If the profile does not require a sandbox (such as unrestricted or disabled), the request becomes a no-op and commands run directly on the host.

Invoking the Built-in ask Tool

The ask tool provides a convenient shortcut that automatically triggers sandbox boundary requests.

// Using the built-in ask tool with default workspace-write profile
await session.runTool('ask', { prompt: 'Read confidential file?' });

When invoked, ask starts with the managed workspace-write profile, which automatically demands a sandbox boundary and triggers the approval flow through SandboxManager.

React UI Integration

For frontend applications, use the useSandboxBoundary hook to request boundaries interactively.

import { useSandboxBoundary } from '@maka/ui';

function MyComponent() {
  const requestSandbox = useSandboxBoundary();
  
  return (
    <button onClick={() => requestSandbox('workspace-write')}>
      Request Sandbox
    </button>
  );
}

The Sandbox Boundary Request Flow

The request follows a three-stage pipeline from profile configuration to execution.

Step 1: Profile Configuration

Each session maintains an ExecutionBoundary object that records the current sandbox policy. When you call session.setExecutionBoundary(), the system checks whether the requested profile (such as workspace-write or explore) mandates OS-level isolation.

Step 2: User Approval

If the active profile requires sandboxing, the UI component sandbox-boundary-prompt (located in packages/ui/src/components/sandbox-boundary-prompt.tsx) renders a dialog requesting user consent. This component is wired directly to the SandboxManager, which validates the request against current capabilities.

Step 3: Platform-Specific Execution

After approval, the SandboxManager (implemented in packages/runtime/src/sandbox/sandbox-manager.ts) transforms the command into a platform-specific launch request. For example, on macOS it wraps commands with sandbox-exec, while on Linux it uses Bubblewrap parameters. The Runtime Host later executes this transformed request; the SandboxManager does not spawn processes directly.

Core Files and Implementation Details

Understanding the source structure helps debug boundary requests. Key files include:

• packages/runtime/src/sandbox/README.md: Contains the architecture overview and policy contracts for sandbox boundaries.
• packages/runtime/src/sandbox/types.ts: Defines ExecutionBoundary interfaces and sandbox selection enums.
• packages/runtime/src/sandbox/sandbox-manager.ts: Core logic that selects platform backends and transforms commands into sandbox-aware execution requests.
• packages/ui/src/components/sandbox-boundary-prompt.tsx: React component handling user approval dialogs.
• packages/runtime/src/__tests__/sandbox-manager.test.ts: Test suite demonstrating validation and transformation logic.

Summary

• Request a sandbox boundary by setting an ExecutionBoundary profile (such as workspace-write) on a Session via session.setExecutionBoundary().
• The ask tool automatically triggers boundary requests using its default workspace-write profile.
• User approval occurs through the sandbox-boundary-prompt component before execution proceeds.
• The SandboxManager generates platform-specific commands (sandbox-exec, Bubblewrap, or AppContainer) but delegates actual execution to the Runtime Host.
• Profiles like unrestricted or disabled bypass sandboxing entirely.

Frequently Asked Questions

What happens if a sandbox is unavailable on the host system?

If you set require: true in the ExecutionBoundary configuration and the host lacks sandbox support, the operation fails immediately according to packages/runtime/src/sandbox/sandbox-manager.ts logic. Without the require flag, the system falls back to direct host execution with appropriate warnings.

Can I request a sandbox boundary without user interaction?

No. The sandbox-boundary-prompt component in packages/ui/src/components/sandbox-boundary-prompt.tsx requires explicit user approval before the SandboxManager transforms commands. This security constraint prevents automated systems from silently elevating privileges.

How do I disable sandbox boundaries for specific operations?

Set the ExecutionBoundary profile to unrestricted, disabled, or external. These profiles bypass the SandboxManager's transformation logic and execute commands directly on the host OS without isolation checks.

What is the difference between workspace-write and explore profiles?

Both profiles require sandbox boundaries, but workspace-write specifically restricts operations to the workspace directory with write permissions, while explore typically grants broader read access within defined limits. Check packages/runtime/src/sandbox/types.ts for the complete enum definitions and policy contracts.

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