How Maka Handles Secrets and Tool Execution Across Sandbox Boundaries

Maka isolates sessions inside sandbox boundaries and manages cross-boundary execution through explicit user-approved expansions, keeping secrets segregated in a secretMaterial structure that is only accessible to built-in tools.

The Apache Maka project implements a defense-in-depth security model where each session operates within a constrained ExecutionBoundary that governs filesystem and network access. When tools require elevated privileges or sensitive credentials, the runtime orchestrates boundary expansions and secret injection without ever exposing sensitive data to user-supplied code.

Secret Handling Architecture

Maka’s secret management is tightly coupled with its runtime policy system to ensure credentials never leak into untrusted execution contexts.

Runtime Policy and Secret Material Structure

According to the apache/maka source code, secrets are stored in a secretMaterial structure defined in [packages/storage/src/runtime-policy/operations.ts](https://github.com/apache/maka/blob/main/packages/storage/src/runtime-policy/operations.ts). This object attaches to runtime-policy operations and supports three distinct credential types:

• secretMaterial.connection.secret – Credentials for network connections (e.g., API keys).
• secretMaterial.networkProxy.secret – Authentication for proxy servers.
• secretMaterial.requestHeaders.secret – Secret-based HTTP headers injected into requests.

This design ensures that secrets are never exposed to user-supplied code; they are only passed to built-in tool implementations that know how to consume them.

Secret Validation and Constraints

Before any secret is utilized, the runtime validates the operation through functions in [packages/core/src/sandbox-boundary.ts](https://github.com/apache/maka/blob/main/packages/core/src/sandbox-boundary.ts). The validateSandboxBoundaryExpansion and applySandboxBoundaryExpansion functions enforce strict size caps and prevent cross-target leakage. Additionally, secret material is automatically stripped when a boundary is downgraded or when the session terminates, ensuring no residual credentials persist in memory.

Cross-Boundary Tool Execution Workflow

When a session requires capabilities that exceed its current ExecutionBoundary—such as network access or broader filesystem rights—it must explicitly request an expansion.

Requesting Boundary Expansion with request_sandbox_boundary

Sessions initiate cross-boundary execution by invoking the request_sandbox_boundary tool. This tool creates a SandboxBoundaryRequest object (see lines 76-95 in [sandbox-boundary.ts](https://github.com/apache/maka/blob/main/packages/core/src/sandbox-boundary.ts)), which captures the requested expansion and justification. The request is stored and presented to the user or host for review.

// Request network access for external API calls
await tools.request_sandbox_boundary({
  expansion: { network: { enabled: true } },
  justification: "Need to call an external API"
});

The Approval and Expansion Process

If the user approves the request, the host expands the session’s boundary through a controlled pipeline:

1. assessSandboxBoundaryExpansion – Evaluates the requested changes against existing policies.
2. applySandboxBoundaryExpansion – Applies the validated changes to the session context.
3. createManagedExecutionBoundary – Generates a new boundary object with the granted permissions.

If the user denies the request, the operation is marked denied and any pending tool execution aborts with a SandboxCommandError.

The system actively prevents privilege escalation through expansionConflictsWithExplicitDeny, which checks the expansion against explicit deny rules and protected metadata before approval.

Safety Guarantees and Capacity Limits

Maka enforces hard constraints to prevent abuse of boundary expansions:

• Maximum 32 filesystem entries per expansion request.
• 4 KB path length limit for filesystem entries.
• 64 KB serialized payload limit for boundary requests.
• Conflict checks ensure that a boundary request cannot silently override an existing deny rule.

Once approved, the tool executes with the newly granted permissions, and any required secrets are supplied from the associated secretMaterial structure.

Practical Implementation Examples

The following patterns demonstrate how to work with secrets and boundary expansions in Maka:

// Example 1: Using secretMaterial with the web-fetch tool
const result = await tools.web_fetch({
  url: "https://api.example.com/data",
  // The API key is injected via secretMaterial, not inline
  secretMaterial: { connection: { secret: process.env.MY_API_KEY } }
});

// Example 2: Requesting filesystem write access
await tools.request_sandbox_boundary({
  expansion: {
    filesystem: {
      entries: [{ path: "/workspace/tmp", access: "write", scope: "subtree" }]
    }
  },
  justification: "Write temporary files for processing"
});

Summary

• Maka uses an ExecutionBoundary object to isolate sessions, controlling filesystem and network access.
• Secrets are encapsulated in secretMaterial structures attached to runtime-policy operations, ensuring they remain inaccessible to user code.
• Cross-boundary tool execution requires explicit user approval via request_sandbox_boundary, which creates a SandboxBoundaryRequest processed through assessSandboxBoundaryExpansion and applySandboxBoundaryExpansion.
• Hard capacity limits (32 filesystem entries, 4 KB paths, 64 KB payloads) and conflict checks prevent privilege escalation and resource exhaustion.
• Once approved, tools receive secrets only through the secretMaterial interface defined in packages/storage/src/runtime-policy/operations.ts.

Frequently Asked Questions

How does Maka prevent secrets from leaking to user-supplied code?

Maka stores all credentials in a secretMaterial structure that is attached to runtime-policy operations in packages/storage/src/runtime-policy/operations.ts. This structure is only accessible to built-in tool implementations that consume the secrets, while user-supplied code receives no access to the raw credential values. The runtime strips secret material when boundaries are downgraded or sessions end.

What happens when a sandbox boundary request is denied?

If a user or host denies a SandboxBoundaryRequest, the request is marked as denied in the system state. Any pending tool execution that depends on the expanded boundary aborts immediately with a SandboxCommandError, preventing the session from proceeding with operations that exceed its current permissions.

What are the capacity limits for sandbox boundary expansions?

According to the implementation in packages/core/src/sandbox-boundary.ts, boundary expansions are capped at 32 filesystem entries, 4 KB maximum path length per entry, and 64 KB for the serialized payload. These limits are enforced by validateSandboxBoundaryExpansion to prevent resource exhaustion and denial-of-service attacks.

Where is the ExecutionBoundary defined in the codebase?

The ExecutionBoundary object and its associated validation logic are defined in [packages/core/src/sandbox-boundary.ts](https://github.com/apache/maka/blob/main/packages/core/src/sandbox-boundary.ts). The actual tool implementation that creates boundary requests resides in [packages/runtime/src/sandbox-boundary-tool.ts](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox-boundary-tool.ts), while the host-side authority that consumes secrets is located in [packages/runtime-host/src/server/execution-model-authority.ts](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/execution-model-authority.ts).

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