How Mako Enforces Sandboxed Execution and File System Restrictions for Tools

Mako isolates tool execution using a dedicated Windows AppContainer launched by the Maka Windows Sandbox binary, enforcing strict file system access through runtime policies and an ACL ledger that whitelists only explicitly mounted directories.

The apache/maka repository implements a defense-in-depth sandboxing architecture that prevents tools from escaping their execution environment or accessing unauthorized host resources. By combining Windows AppContainer isolation with explicit runtime policies and path-based access controls, Mako ensures that every tool operates within a minimal, well-defined security boundary.

Windows AppContainer Isolation

Mako leverages the Windows AppContainer mechanism to create kernel-level isolation between the host and tool processes. The sandbox is provisioned by the Rust-based launcher and orchestrated through the JavaScript SandboxManager.

Sandbox Launcher and Manifest Creation

The sandbox creation process begins in experiments/windows-sandbox/launcher/src/main.rs, where the launcher constructs a sandbox manifest specifying AppContainer capabilities, job objects, and network restrictions. This manifest, written to packaged-sandbox-manifest.json, declares exactly which host directories are mounted inside the container and what system resources the tool may access.

The launcher binary generates these capabilities dynamically based on the tool's declared requirements, ensuring no container receives broader permissions than necessary.

Runtime Policy Enforcement

Inside the container, Mako applies a strict runtime policy defined in packages/eval/src/maka-runtime-policy.ts that enumerates allowable file system paths, environment variables, and system calls. The policy operates on a default-deny principle, rejecting any operation not explicitly whitelisted.

ACL Ledger and Path Whitelisting

The ACL ledger, implemented in experiments/windows-sandbox/launcher/src/acl_ledger.rs, maintains a HashSet of allowed PathBuf entries and validates every file system operation against this whitelist. The is_allowed method checks if requested paths start with any whitelisted prefix, immediately denying access to locations outside the mounted directories.

// experiments/windows-sandbox/launcher/src/acl_ledger.rs
pub struct AclLedger {
    allowed: HashSet<PathBuf>,
}
impl AclLedger {
    pub fn is_allowed(&self, path: &Path) -> bool {
        self.allowed.iter().any(|p| path.starts_with(p))
    }
}

Any file system call that fails this prefix check is blocked at the sandbox boundary before reaching the host kernel.

Sandbox Management and Tool Invocation

The SandboxManager in sandbox/sandbox-manager.js handles the lifecycle of sandboxed processes, spawning maka-windows-sandbox.exe with the generated manifest and forwarding tool commands into the isolated environment. The manager monitors process termination and ensures cleanup of job objects and temporary ACL ledgers.

// scripts/verify-windows-sandbox-e2e.mjs
const sandboxExecutable = join(resourcesPath, 'windows-sandbox', 'maka-windows-sandbox.exe');
const sandboxManager = new SandboxManager([
  {
    clientPath: sandboxExecutable,
    // only the tool's working directory is exposed
    mounts: [{ hostPath: toolDir, sandboxPath: '/workspace' }],
    policy: 'sandbox/windows-sandbox.js',
  },
]);

await sandboxManager.runTool({
  command: ['node', 'my-tool.js'],
  cwd: '/workspace',
});

The SandboxManager acts as the single control point for spawning, monitoring, and terminating sandboxed tools, preventing resource leaks and ensuring consistent policy application.

File System Restriction Mechanisms

Mako implements multiple layers of file system restrictions to prevent data exfiltration or unauthorized modification:

• Mount restrictions: Only explicitly declared directories are mounted into the sandbox namespace
• ACL enforcement: The ACL ledger denies all paths outside the whitelisted set
• Policy validation: The runtime policy rejects file system operations that violate security rules

// packages/eval/src/maka-runtime-policy.ts
export const runtimePolicy = {
  // whitelist of accessible paths
  allowedPaths: ['/workspace', '/tmp'],
  // deny all other file system operations
  denyAll: true,
  // environment variables that may be passed
  allowedEnv: ['PATH', 'HOME'],
};

These layers work sequentially: the AppContainer blocks kernel-level access, the mount namespace limits visible directories, and the runtime policy provides application-level enforcement.

Summary

• Mako uses Windows AppContainer isolation via maka-windows-sandbox.exe to create kernel-level process boundaries
• The Rust-based launcher in experiments/windows-sandbox/launcher/src/main.rs generates capability manifests and ACL ledgers that whitelist only necessary file system paths
• The AclLedger struct enforces path-based restrictions by verifying all file operations against allowed prefixes
• The JavaScript SandboxManager orchestrates sandbox lifecycle, mounting only explicit directories and applying runtime policies
• File system access is restricted through three layers: container capabilities, mount namespaces, and TypeScript runtime policy validation

Frequently Asked Questions

What is the Maka Windows Sandbox?

The Maka Windows Sandbox is a dedicated binary (maka-windows-sandbox.exe) that creates and manages Windows AppContainer instances for tool isolation. According to the apache/maka source code, this executable is launched by the JavaScript SandboxManager and interprets the packaged-sandbox-manifest.json to configure container capabilities, network restrictions, and allowed file system mounts before spawning the tool process.

How does Mako prevent tools from accessing arbitrary host files?

Mako prevents arbitrary file access through a whitelist-based approach implemented in the ACL ledger (experiments/windows-sandbox/launcher/src/acl_ledger.rs). The ledger maintains a HashSet of allowed paths and checks every file system request using the is_allowed method. Combined with the runtime policy in packages/eval/src/maka-runtime-policy.ts that sets denyAll: true, any attempt to read or write outside explicitly mounted directories is rejected at multiple enforcement points.

Where is the sandboxing policy defined and enforced?

The sandboxing policy is defined in packages/eval/src/maka-runtime-policy.ts and enforced at two levels. First, the Rust launcher creates an AppContainer with restricted capabilities based on the manifest. Second, the runtime policy applies application-level controls inside the container, specifying allowed paths, environment variables, and system call permissions. This dual-layer approach ensures policy enforcement even if one layer is compromised.

How does the SandboxManager handle tool execution?

The SandboxManager (sandbox/sandbox-manager.js) instantiates sandbox configurations containing the executable path, mount points, and policy file, then spawns the sandbox process with these parameters. It forwards the tool's command arguments into the isolated environment, monitors the process for unexpected termination, and manages cleanup of system resources including job objects and temporary ACL ledgers when execution completes.

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