Documentation feedback: .cursorignore, Sandbox Mode, and wildcard performance in large repositories

Ideas Feedback
, , , ,
1

Hi Cursor / Anysphere team,

I would like to share a few observations from evaluating Cursor’s Sandbox Mode in a more security-conscious enterprise setup. This is meant both as feedback and as a request to clarify or extend the documentation.

Setup

I am working with large repositories containing several tens of thousands of source files. My host system is macOS, and I use an Ubuntu-based Dev Container. I am currently evaluating Cursor’s Sandbox Mode for use in our company.

During this evaluation I noticed two things that, at least from my perspective, are not sufficiently clear in the current documentation.

1. .cursorignore appears to be enforced by the sandbox, but the documentation is unclear or contradictory

In my setup I can reliably reproduce that files excluded via .cursorignore cannot be read by terminal commands executed inside the sandbox. For example, if a file is excluded in .cursorignore, a simple read access from inside the sandbox fails.

This is very useful and exactly the kind of behavior I would like to rely on in an enterprise environment.

However, the current documentation still says that terminal and MCP server tools used by Agent cannot block access to code governed by .cursorignore:

At the same time, there are several Cursor sources that suggest or explicitly confirm that .cursorignore is in fact part of the sandbox behavior:

The main issue for me is not the behavior itself. The behavior is actually very helpful.

The issue is that the official documentation and the observed / confirmed behavior do not fully match. In an enterprise context this is difficult, because security-related approvals and internal documentation need to rely on stable, documented behavior. Relying on a feature that is only described in blog posts or forum replies is much harder than relying on official product documentation.

It would be very helpful if the official documentation could explicitly clarify:

  • whether .cursorignore is intentionally enforced by Sandbox Mode;
  • whether this behavior is considered a stable security boundary;
  • whether this applies consistently to terminal commands inside Dev Containers;
  • which limitations or known exceptions exist;
  • whether there are differences between macOS, Linux, Windows/WSL, and Dev Containers.

2. Wildcards in .cursorignore can make sandbox startup very expensive in large repositories

I also observed a strong relationship between wildcard patterns in .cursorignore, repository size, and the startup time of sandboxed commands.

My test case is intentionally trivial: I ask Cursor to run whoami.

In one of my repositories with several tens of thousands of files, sandboxed execution can take several minutes, even for this trivial command.

My .cursorignore contains a few explicitly listed files using exact paths, plus one wildcard pattern:

*.env

When I remove this single wildcard from .cursorignore, sandboxed command execution is effectively instant. I do not notice a meaningful performance penalty.

When I add the wildcard back, sandbox setup becomes very expensive again, and even whoami can take several hundred seconds before it runs.

This seems technically understandable. If the sandbox needs to resolve glob patterns and make all matching files inaccessible before the command starts, it may need to walk a large portion of the repository or filesystem and then create many deny mappings or mounts. In very large repositories, that cost can become significant.

There is a related forum thread that appears to describe a similar root cause:

In that thread, Dean states that the root cause is file-glob patterns from ~/.cursorignore creating bind mounts for individual files, and that walking the relevant file tree is expected to add overhead.

My request here would be to document this behavior as an operational best practice.

For large repositories, users should probably avoid broad wildcard patterns in .cursorignore when they want to use Sandbox Mode efficiently. Instead, sensitive files should preferably be listed explicitly by path wherever possible.

For example, in large repositories this may be much better:

app/backend/.env
app/frontend/.env
deployment/local/.env

than this:

*.env

I understand that this may not be a simple bug that can be fully optimized away. In fact, I would be cautious about relying too much on caching for a security-sensitive feature like this. I would mainly appreciate clear documentation so teams can make informed trade-offs.

Suggested documentation additions

It would be very helpful if the documentation included a short section along these lines:

When Sandbox Mode is enabled, .cursorignore entries are also used to restrict filesystem access for sandboxed terminal commands. On Linux, including Dev Containers, this is enforced through the sandbox filesystem layer. Broad glob patterns may require scanning many files and can significantly increase sandbox startup time in large repositories. In addition, sandbox implementations may be subject to practical limits on the number of ignored files that can be mapped or mounted. For best performance and reliability, prefer explicit paths for sensitive files where possible and avoid overly broad glob patterns in large repositories.

I believe this would make the feature much easier to evaluate and adopt in enterprise environments.

Another documentation improvement that would be very valuable would be an explicit overview table describing how Sandbox Mode is implemented across different environments and what practical limitations follow from each implementation. For example, a table could map operating systems and execution environments (macOS, Linux, Windows/WSL, Dev Containers, etc.) to the underlying sandboxing technique, the scope of .cursorignore enforcement, known limitations, performance considerations, and recommended best practices. I am not suggesting that such a table needs to be included here, but having a single authoritative reference of this kind would make it much easier for security teams and administrators to understand the guarantees and trade-offs of each platform configuration.

Thanks a lot for the work on Sandbox Mode. The feature is very valuable, and these clarifications would make it much easier to use confidently in larger and more security-conscious setups.

Best regards,
Simon

6

Hey @Der_Simon

Thanks for the feedback. Let me try and clarify how this is works (and suggest two changes we can make to our docs)

.cursorignore and the Sandbox are both distinct and complementary.

  1. Cursor’s built-in agent tools (file read, write, edit, grep, list-dir) always check .cursorignore, regardless of sandbox mode. This is why the Read tool correctly returns “Permission denied” on a .cursorignore’d file.
  2. The sandbox filesystem layer enforces .cursorignore for terminal/shell commands, but only for commands that actually run inside the sandbox. On macOS that’s a Seatbelt deny (“Operation not permitted”); on Linux it’s a zero-permission bind mount.

So the docs line about terminal/MCP tools “not blocking” .cursorignore is the baseline. This is probably the distinction that we should add to the docs. Something like:

The terminal and MCP server tools used by Agent cannot block access to code governed by .cursorignore, except for terminal commands run inside the sandbox.

WDYT?

On performance – I wasn’t able to reproduce what you mentioned around the wildcards! Can you confirm what version of Cursor you’re using?

7

Hi Colin,

thanks a lot for the detailed clarification. This is really helpful for us, and the documentation change you suggested sounds good to me. I think adding that distinction explicitly would make the behavior much easier to understand and rely on.

I may also have to apologize a little: I noticed that the sandbox documentation links to the blog post explaining the implementation details. We may have missed that before, or simply looked for the information in the wrong way. Since the blog post is linked from the docs, I would personally consider it part of the documentation, so our main need for understanding how the sandbox works is mostly covered.

That said, it would still be even better if the docs themselves contained a short, explicit summary of the guarantees provided by the sandbox, without requiring that extra indirection through the blog post.

Regarding performance: in my projects, I can observe very different sandbox setup times, sometimes even several minutes before a simple terminal command starts executing.

To better understand whether this is related to .cursorignore, I created a synthetic test project with several hundred thousand empty files and experimented with different .cursorignore entries. However, I could not establish a clear connection between wildcard patterns in .cursorignore and the execution time of terminal commands in the sandbox.

In that synthetic setup, I still see sandboxed command (whoami) runtimes ranging from about 15 seconds to almost a minute, which is quite a large variation and still relatively slow.

Do you have any tips on how this could be optimized? For example, are there things we can improve in the Dev Container setup, or tools that should be available inside the container to make sandbox initialization faster? I would also be interested to know whether the large variation in setup time is expected, known, or something you can explain.

I’m currently using Cursor version:

Version: 3.7.36 (Universal)
VS Code Extension API: 1.105.1
Commit: 776d1f9d76df50a4e0aeca61819a88e7c1b861e0
Date: 2026-06-13T00:31:56.287Z
Layout: editor
Build Type: Stable
Release Track: Default
Electron: 39.8.1
Chromium: 142.0.7444.265
Node.js: 22.22.1
V8: 14.2.231.22-electron.0
xterm.js: 6.1.0-beta.256
OS: Darwin arm64 25.5.0

Thanks again for taking the time to explain this. The clarification already helps a lot.