SOP-008: Terminal Integration

Document Control

Field	Value
SOP ID	SOP-008
Version	1.0
Status	Active
Last Updated	2024-12

Purpose

This SOP covers Cursor's terminal integration, including sandbox execution, command approval, and auto-run configuration.

Scope

• Sandbox mode (macOS)
• Command approval workflow
• Allowlist configuration
• Enterprise controls

Prerequisites

• Cursor installed
• Understanding of Agent Chat (SOP-006)

---

Procedure

Terminal Integration Overview

Three Execution Modes:

Mode	Description	Platform
Sandbox	Auto-runs in restricted environment, blocks unauthorized access	macOS
Ask Every Time	Shows approval prompt for each command	Windows/Linux default
Run Everything	Full trust, no approval needed	All (experienced users)

Step 1: Understand Sandbox (macOS)

The sandbox restricts what commands can do:

Access Type	Sandbox Behavior
File Read	Allowed (full filesystem)
File Write	Workspace directories only
Network	Blocked by default (configurable)
Temp Files	Full access to /tmp/
.cursor folder	Always protected

Implemented using: macOS sandbox-exec

Platform Support

Sandbox is currently macOS only. Linux support coming soon. Windows users can use WSL or devcontainers.

Step 2: Configure Auto-Run Mode

Navigate to: Settings → Cursor Settings → Agents → Auto-Run

Setting	Description
Run in Sandbox	Commands auto-run in sandbox (macOS)
Ask Every Time	All commands require approval
Run Everything	No approval needed

Recommended Settings:

• macOS: Run in Sandbox
• Windows/Linux: Ask Every Time

Step 3: Handle Command Approval

When Agent wants to run a command:

Agent wants to run: npm install express cors

Options: [Run] [Skip] [Add to Allowlist]

Option	Result
Run	Execute once
Skip	Cancel, try alternative
Add to Allowlist	Always allow this command

Step 4: Manage Allowlist

Commands on the allowlist run without approval:

Add to Allowlist:

1. When prompted, click "Add to allowlist"
2. Or: Settings → Cursor Settings → Agents → Command Allowlist

Common Allowlist Commands:

npm install
npm run
yarn
pnpm
git status
git diff
git log
python -m pytest
cargo build
cargo test

Step 5: Configure Network Access

For sandbox mode, network is blocked by default.

Enable Network: Settings → Cursor Settings → Agents → Auto-Run Network Access

Use Cases for Network:

• Installing packages (npm install)
• API testing
• Git push/pull operations

Step 6: Git Operations

Special handling for Git commands:

Setting	Behavior
Allow Git Writes (enabled)	git commit, git push run in sandbox
Allow Git Writes (disabled)	Git write operations require approval

Push Requires Network

git push needs both Git Writes enabled AND Network Access for sandbox mode.

---

Additional Protection Settings

Setting	Description
Browser Protection	Prevent auto-running browser tools
File-Deletion Protection	Require approval for file deletes
Dotfile Protection	Protect .gitignore and similar files
External-File Protection	Protect files outside workspace

Configure in: Settings → Cursor Settings → Agents

---

When Sandbox Commands Fail

If a sandboxed command fails due to restrictions:

Command failed: curl https://api.example.com/data

Reason: Network access blocked

Option	Result
Skip	Let Agent try alternative
Run	Run outside sandbox once
Add to Allowlist	Run outside sandbox always

---

Troubleshooting Shell Themes

Heavy shell themes can interfere with terminal output:

Problem: Truncated or misformatted output with Powerlevel10k/Powerlevel9k

Solution: Detect Cursor Agent and disable theme:

For Zsh (~/.zshrc):

if [[ -n "$CURSOR_AGENT" ]]; then
  # Skip theme initialization for Agent sessions
else
  [[ -r ~/.p10k.zsh ]] && source ~/.p10k.zsh
fi

For Bash (~/.bashrc):

if [[ -n "$CURSOR_AGENT" ]]; then
  PS1='\u@\h \W \$ '
fi

---

Enterprise Controls

For Enterprise subscriptions, admins can override settings:

Admin Setting	Description
Auto-Run Controls	Enable/disable user auto-run settings
Sandboxing Mode	Force sandbox for all users
Sandbox Networking	Control network access
Terminal Command Allowlist	Organization-wide allowlist
Enable Run Everything	Allow users to enable full trust

Configure at: cursor.com/dashboard → Settings → Auto-Run

---

Verification Checklist

• [ ] Auto-Run mode configured appropriately
• [ ] Sandbox works (macOS) - commands run automatically
• [ ] Command approval prompt appears when needed
• [ ] Can add commands to allowlist
• [ ] Network access setting works as expected
• [ ] Protection settings enabled for sensitive operations

Troubleshooting

Issue	Solution
Commands always asking	Check auto-run mode setting
Sandbox failing	Verify macOS, check permissions
Network commands blocked	Enable network access in settings
Output formatting broken	Disable shell theme for Agent
Git push failing	Enable both Git Writes and Network

See Also

• SOP-006: Agent Chat
• SOP-013: CLI Installation
• SOP-015: Team & Enterprise