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

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. 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 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, 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) 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
Network Egress Blocking	Disables native networking APIs unless explicitly granted via approval	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
Deterministic Replay	Persists all tool calls and results to enable state reconstruction without re-execution	packages/runtime/src/log/RuntimeEventLog.ts
Policy Hooks	Reads runtime-policy.json at startup to merge project-specific allow/deny lists with built-in rules	packages/runtime/src/tool/ToolRuntime.ts

Practical Implementation Examples

CLI Invocation and Approval Prompts

# 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

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 file at the workspace root:

{
  "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 that isolates filesystem and network access.
• Explicit approval via ToolApproval.ts is required for any operation escaping the sandbox boundary.
• Comprehensive logging in 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 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 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.

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