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

> Learn how to request a sandbox boundary in Apache Maka by configuring an ExecutionBoundary profile and approving the prompt. A complete guide for developers.

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

---

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

```typescript
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.

```typescript
// 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.

```tsx
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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/README.md): Contains the architecture overview and policy contracts for sandbox boundaries.
- [`packages/runtime/src/sandbox/types.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/types.ts): Defines `ExecutionBoundary` interfaces and sandbox selection enums.
- [`packages/runtime/src/sandbox/sandbox-manager.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/ui/src/components/sandbox-boundary-prompt.tsx): React component handling user approval dialogs.
- [`packages/runtime/src/__tests__/sandbox-manager.test.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/types.ts) for the complete enum definitions and policy contracts.