Cursor CLI: a locked-down headless mode (file tools only, no hooks/MCP/plugins, enforced tool allowlist)

Ideas Feature Requests
,
1

Feature request for product/service

Cursor CLI

Describe the request

I run cursor-agent headless (--print --output-format stream-json, prompt on stdin, explicit
--resume) from a local tool that automates coding tasks on Windows 11. Every run needs a fixed,
checkable permission profile: file tools inside the workspace only — no shell, no web tools, no
MCP servers, no hooks, no plugins — while our organization’s managed team policy stays in force.
If I cannot establish that profile, the tool does not launch Cursor at all.

With build 2026.09.26-dd393fe I could not establish it:

  • Plugins enabled for the account in the dashboard still appear to load, even with a fresh
    CURSOR_CONFIG_DIR and home directory.
  • --disable-project-configs only skips .cursor/cli.json; project hooks.json, mcp.json,
    the plugins key in .cursor/settings.json and third-party imports still apply.
  • The CLI accepts hidden --allowed-tools / --exclude-tools options marked “internal only”.
    They are sent as request headers, and it is not documented whether they are enforced,
    including for subagents.
  • On Windows there is no filesystem sandbox; the file tools have built-in exceptions outside the
    workspace (temporary files, generated artifacts, .cursor rule files in the home directory),
    and permission patterns appear to match case-sensitively.
  • With a fresh config directory, the team falls back to the server default.

What would solve it

  1. One documented switch for a locked-down headless session, e.g. --locked-down: no user
    or project hooks, no MCP servers, no plugins (local, marketplace, dashboard-enabled), no
    third-party imports, no subagent definitions — while instruction files (AGENTS.md,
    .cursor/rules, skills) and team-managed policy still apply.
  2. A documented, enforced tool allowlist, e.g. --tools read,list,glob,grep,edit,write,delete:
    nothing else is offered to the model or executed by the client — including shell, web
    search/fetch, image generation, semantic search and subagents (or at least subagents pinned
    to the requested model).
  3. A workspace-only file boundary on Windows in that mode: checked on resolved paths
    (symlinks, junctions), case-insensitive, no exceptions outside the workspace, and a visible
    error result instead of a prompt or a hang.
  4. A way to inspect the effective configuration without a model turn, e.g.
    cursor-agent config --effective --json: plugins, hooks, MCP servers, permissions and the
    active team for an account and workspace.
  5. A flag or environment variable that pins the team for headless runs, reported in
    system/init.

Nice to have: a documented stream-json schema (tool-call variants, interaction_query, usage);
--new-session-id and the storage-root variables (CURSOR_CONFIG_DIR, CURSOR_ CURSOR_AGENT_STORE_DIR) as supported options; and a guarantee that an explicit –model` never
falls back to another model.

Why it matters

Headless automation needs runs that are predictable and auditable. Today the eff
capabilities of a run depend on dashboard settings, project files and server defaults that the
caller can neither pin nor inspect. A locked-down mode would let teams automate
while their managed policy stays authoritative.

Operating System: Windows 11 (cursor-agent 2026.09.26-dd393fe)

Happy to test preview builds and report back.

Operating System (if it applies)

Windows 10/11

7

Hey @Sven_Engels, thanks for the detailed write-up.

We’ve let the team know. A documented headless mode that limits runs to workspace file tools, keeps team policy in force, and lets you inspect and pin that profile is not available in the CLI today.

I’ll post here when there’s an update.

8

Since a locked-down mode isn’t available yet, here’s what I’d do so the profile is enforced by something other than Cursor’s own config:

  1. OS boundary first. Run cursor-agent as a separate local Windows user whose NTFS ACLs allow write-only access to the workspace folder (and whatever Cursor needs for its own store). Then “no writes outside the workspace” is enforced by Windows on resolved paths, symlinks, and junctions included, not by pattern matching. It doesn’t cover reads or network, but it’s the part you can actually guarantee today.

  2. Check every tool call in your wrapper. stream-json emits a tool_call “started” event per call (readToolCall, writeToolCall, others as tool_call.function with a name). Keep an allowlist of tool types, and on the first event outside it, kill the process tree and mark the run failed. Docs: Output format | Cursor Docs
    One caveat: I couldn’t confirm the started event always arrives before the tool executes, so treat this as detect-and-abort plus an audit log, not prevention. That’s why step 1 matters.

  3. Log the system/init event and the full stream per run. The docs say tools and mcp_servers may be added to init later. When that lands, you can refuse to continue if anything unexpected is listed, which gets you most of the “inspect effective config” ask.

Not a replacement for what you asked for, but it gives you a profile you can check, and a run that fails closed when something outside it shows up.