# How Maka's Tool Runtime Executes Tools Safely: Inside the Sandbox Architecture

> Discover how Maka's Tool Runtime executes tools safely within its sandbox architecture. Learn about filesystem restrictions, network blocking, and explicit user approval for secure tool execution.

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

---

**Maka's Tool Runtime isolates every tool invocation inside a sandboxed environment that restricts filesystem access to the workspace, blocks network egress by default, and mandates explicit user approval before executing potentially dangerous operations.**

The execution safety model in `apache/maka` centers on the **Tool Runtime**, a component designed to run arbitrary user tools—from simple file reads to complex shell commands—without compromising host system integrity. By combining filesystem isolation, policy-driven approval workflows, and durable execution logging, Maka's Tool Runtime ensures that even untrusted code runs within strictly defined boundaries.

## The Three Pillars of Tool Runtime Safety

According to the source code in `packages/runtime/src/tool/`, the safety architecture rests on three foundational pillars:

### Sandbox Boundary Isolation

Every tool call passes through a sandbox defined in [`packages/runtime/src/sandbox/Sandbox.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/Sandbox.ts). This sandbox limits filesystem access to the current workspace directory, prevents network egress, and enforces a whitelist of allowed system calls. The runtime resolves all relative paths against the workspace root and rejects attempts to traverse outside using `..` patterns.

### Explicit Approval Workflow

When a tool request violates sandbox constraints—such as a `Bash` command attempting to write outside the workspace—the `ToolApproval.prompt()` method in [`packages/runtime/src/tool/ToolApproval.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool/ToolApproval.ts) interrupts execution. The runtime displays the requested command and target resources, requiring the user to **allow**, **deny**, or **modify** the call before dispatch.

### Execution Classification and Abort

The runtime monitors execution through [`packages/runtime/src/tool/ToolExecution.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool/ToolExecution.ts), classifying results as **success**, **failure**, **aborted**, or **unsafe**. If a safety violation is detected or the user cancels the operation, the runtime immediately terminates the tool and records the classification in the durable execution log.

## Execution Flow Through ToolRuntime.ts

The `ToolRuntime.execute()` method orchestrates the entire lifecycle of a tool call:

1. **Request Creation**: A model generates a `ToolCall` object (defined in [`packages/runtime/src/tool/ToolCall.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool/ToolCall.ts)) containing the tool name, arguments, and an optional `sandboxToken`.

2. **Sandbox Validation**: The runtime invokes `Sandbox.validateCall()` to verify requested paths remain inside the allowed workspace and that no prohibited capabilities (network, privileged process) are present.

3. **User/Policy Approval**: If validation detects a boundary violation, `ToolApproval.prompt()` triggers an interactive CLI prompt or desktop modal.

4. **Safe Dispatch**: Upon approval, the tool launches inside a child process with a locked-down environment (using `node:child_process` with restricted `execPath` and `PATH`). The runtime captures stdout, stderr, and exit codes.

5. **Result Recording**: `ToolRuntime.recordResult()` writes a `ToolResult` entry to the **Runtime Event Log** (`runtime.sqlite`), storing the original request, sandbox token, execution outcome, and safety metadata for audit and replay.

## Key Safety Mechanisms and Resource Controls

The Tool Runtime implements multiple layers of defense:

| Mechanism | Implementation | Source File |
|-----------|---------------|-------------|
| **Filesystem Isolation** | Mounts workspace as the only writable directory; rejects path traversal attempts | [`packages/runtime/src/sandbox/Sandbox.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/Sandbox.ts) |
| **Network Egress Blocking** | Disables native networking APIs unless explicitly granted via approval | [`packages/runtime/src/sandbox/Sandbox.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox/Sandbox.ts) |
| **Resource Quotas** | Enforces CPU and memory limits via `worker_threads` with `resourceLimits`; auto-terminates exceeding processes | [`packages/runtime/src/tool/ToolRuntime.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool/ToolRuntime.ts) |
| **Deterministic Replay** | Persists all tool calls and results to enable state reconstruction without re-execution | [`packages/runtime/src/log/RuntimeEventLog.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/log/RuntimeEventLog.ts) |
| **Policy Hooks** | Reads [`runtime-policy.json`](https://github.com/apache/maka/blob/main/runtime-policy.json) at startup to merge project-specific allow/deny lists with built-in rules | [`packages/runtime/src/tool/ToolRuntime.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool/ToolRuntime.ts) |

## Practical Implementation Examples

### CLI Invocation and Approval Prompts

```bash

# Safe file read inside workspace

maka run "Read" --args '{"path":"docs/README.md"}'

# Dangerous command triggers approval modal

maka run "Bash" --args '{"command":"rm -rf /"}'

# Output: Prompt: "The command wants to delete files outside the workspace. Allow?"

```

### Programmatic Tool Execution

```typescript
import { ToolRuntime } from '@maka/runtime';

const call = {
  name: 'Write',
  args: { path: 'temp/output.txt', content: 'Hello, Maka!' },
  sandboxToken: 'workspace-123'
};

try {
  const result = await ToolRuntime.execute(call);
  console.log('Tool succeeded:', result);
} catch (e) {
  console.error('Tool failed or was unsafe:', e);
}

```

### Custom Policy Configuration

Create a [`runtime-policy.json`](https://github.com/apache/maka/blob/main/runtime-policy.json) file at the workspace root:

```json
{
  "disallowedTools": ["Bash"],
  "allowedPaths": ["src/**", "docs/**"]
}

```

This configuration automatically rejects all `Bash` calls without prompting, overriding the default approval workflow.

## Summary

- **Maka's Tool Runtime** executes tools inside a strict sandbox defined in [`Sandbox.ts`](https://github.com/apache/maka/blob/main/Sandbox.ts) that isolates filesystem and network access.
- **Explicit approval** via [`ToolApproval.ts`](https://github.com/apache/maka/blob/main/ToolApproval.ts) is required for any operation escaping the sandbox boundary.
- **Comprehensive logging** in [`RuntimeEventLog.ts`](https://github.com/apache/maka/blob/main/RuntimeEventLog.ts) enables audit trails and deterministic replay of executions.
- **Resource quotas** and process isolation prevent denial-of-service attacks through runaway tool execution.
- **Policy configuration** via [`runtime-policy.json`](https://github.com/apache/maka/blob/main/runtime-policy.json) allows projects to define custom security boundaries beyond the defaults.

## Frequently Asked Questions

### What happens if a tool attempts to access files outside the workspace?

The `Sandbox.validateCall()` method detects the path traversal attempt and either rejects the call immediately or triggers `ToolApproval.prompt()` to request user consent. Without explicit approval, the runtime throws a security exception and records the attempt as **unsafe** in the execution log.

### Can network requests be permitted for specific tools?

Yes, but only after explicit approval. The sandbox blocks all network egress by default. When a tool like `Read` requests a remote URL, the runtime presents the target URI to the user through the approval workflow. Once granted, the specific network capability is temporarily enabled for that execution context.

### How does Maka ensure long-running tools don't freeze the system?

The Tool Runtime enforces resource quotas using `worker_threads` with `resourceLimits` options. If a tool exceeds allocated CPU time or memory thresholds, `ToolRuntime.execute()` automatically terminates the child process and returns an **aborted** status, preventing resource exhaustion attacks.

### Where are tool execution results stored for debugging?

All results persist in `runtime.sqlite` via the [`RuntimeEventLog.ts`](https://github.com/apache/maka/blob/main/RuntimeEventLog.ts) module. Each entry contains the original `ToolCall`, the assigned `sandboxToken`, the exit code, captured output streams, and safety classification metadata, enabling developers to replay exact execution sequences during debugging.