Allow overriding `cursorsandbox` helper path or expose `sandboxBinaryPath` configuration for Electron & pnpm environments

[tuhuynh27]

Context

I am embedding @cursor/sdk (verified on version 1.0.19 on macOS arm64) inside a local desktop application built with Electron and managed via pnpm.

The Problem

When attempting to enable the filesystem sandbox using local.sandboxOptions.enabled: true, every agent.send immediately throws the following error:

ConfigurationError: Local SDK sandboxing was requested, but sandboxing is not supported in this environment. Disable local.sandboxOptions.enabled or remove ~/.cursor/sandbox.json to run without sandboxing.

Root Cause Analysis

1. Walk-up Discovery Failure: The SDK currently enforces the filesystem sandbox through the native helper binary (@cursor/sdk-<os>-<arch>/bin/cursorsandbox). To locate this helper, the SDK walks up the directory tree starting from process.argv[1], searching for node_modules/@cursor/sdk-<os>-<arch>/bin/cursorsandbox.
2. Breakage in Modern Tooling (pnpm & Electron):
   • pnpm layout: Packages are stored in a content-addressable store and symlinked under node_modules/.pnpm/@cursor+sdk-<arch>@.../.... The traditional top-level node_modules walk-up strategy cannot resolve this nested layout properly.
   • Electron Main Process: In the Electron main process, process.argv[1] points to the Electron entry script or executable path, not a file structure relative to the SDK's node modules.
   • ASAR Packaging: Once the production app is packaged, the SDK code lives inside app.asar. A native helper binary cannot execute directly from within an ASAR archive, and the internal path resolution completely breaks down.

Current Limitation

There is currently no public API or configuration to explicitly guide the SDK to the binary file. The internal path setter (sandboxBinaryPath or similar) is not exported or accessible via configureCursorSdk or AgentOptions. Discovery is the single point of failure.

Proposed Solution / Feature Request

Please export a configuration option (e.g., sandboxBinaryPath inside configureCursorSdk or AgentOptions) to allow developers to manually supply the absolute path to the native helper binary.

This would allow embedders using Electron or monorepos to extract the cursorsandbox binary using tools like asarUnpack or extraResources and feed the valid runtime path directly into the SDK setup:

// Proposed API usage
configureCursorSdk({
  local: {
    sandboxOptions: { enabled: true },
    sandboxBinaryPath: path.join(__dirname, 'unpacked/bin/cursorsandbox') // Manually provided path
  }
});

Thank you! This flexibility is essential for anyone trying to securely embed the Cursor Agent SDK in production desktop runtime environments.