Cursor Agent: The Terminal Tool

The terminal tool is how the agent runs shell commands. Cursor runs them directly in your terminal, so the output lands where you can read it. Your Run Mode setting, not the tool itself, decides whether a command runs on its own, waits for your approval or goes into the sandbox.

Cursor's docs sum up the terminal page in three things: sandboxing, preserved history and native terminal integration. Sandboxing depends on your Run Mode, as the sandbox section below explains. Preserved history means you can read back what the agent ran. When an agent has been working for twenty minutes and the working tree looks wrong, start with the commands that got it there.

A local agent runs on your machine as you. Cursor's LLM safety docs say agents can read and write the files you can, run the commands you can and reach the network resources you can. Configure the terminal before the other tools, because Run Mode, hooks and the sandbox are what bound that reach, and you set all three. Cloud AgentsAgents that run in a Cursor-managed virtual machine, check out the repo, do the work and open a pull request, then shut down, with no load on your laptop. Press Enter for the full definition. work differently, since each one runs on its own machine.

Run Mode decides. It controls three things for terminal commands: when they run automatically, when Cursor stops to ask you, and when a command enters the sandbox. Set the behavior you want before you let an agent loose on a repo.

On a new machine, check it before the first prompt. Run Mode is easy to miss until you know it exists, and the first sign of it may be a command you would have declined scrolling past. Nothing is usually broken at that point, but checking one setting first makes for a better first hour.

The three modes are Auto-review, which is the default in Cursor 3An older release label for Cursor's multi-agent interface; current product guidance calls the active surface the Agents Window. Press Enter for the full definition..6 and later, plus Allowlist and Run Everything. Which one to pick, and why the classifier inside Auto-review is not a security boundary, is covered in the Auto-review Run Mode guide.

The mode names don't show who bears the cost. Working alone, a strict mode costs you some clicks. On a team, a mode that interrupts constantly tends to get turned off, and then people run looser than the default they started from while believing they have a control.

Set the mode centrally instead. On Enterprise, admins set Run Mode as an org policy from the team dashboard. Without that policy, each developer picks their own.

Write a hook. beforeShellExecution fires before any shell command executes and returns allow, deny or ask. The script is yours and sits with the rest of your config, so the same command gets the same answer every run.

The matcher on beforeShellExecution runs against the full command string, so you can scope the hook. A hook that fires on every command turns into noise within a week. Cursor's own example fires an approval script only when the command contains curl, wget or nc, and stays out of the way for everything else.

The sandbox field tells your script whether the command is about to run inside the sandbox. That is where Run Mode and your own policy meet: your script can allow a sandboxed command that it would deny against the real filesystem.

afterShellExecution audits rather than blocks. Its duration counts execution only and excludes the time spent waiting for approval, so it tells you nothing about how long anyone looked at a prompt. If interruption cost is what you want to size, count approvals instead of timing them.

Exit code 2 from a beforeShellExecution hook blocks the command, and so does a response that isn't valid JSON. A crash, a timeout or any other non-zero exit code fails open by default: Cursor logs the failure and runs the command. Set failClosed to true on the hook definition to block on those failures too, and until you do, treat the hook as best-effort. Where to set it, and where leaving it off is the better call, is covered on security hardening.

The sandbox runs terminal commands in a restricted environment that blocks unauthorized file access and network activity. It applies only in some Run Modes. Under Auto-review, shell commands that aren't on your allowlist run in the sandbox when they can. Allowlist uses the sandbox only when sandboxing is enabled, and Run Everything never uses it.

Cursor blocks files listed in .cursorignore from the agent and from @ mentions, but its ignore-file docs say the agent's terminal tool can't enforce those rules. A command the agent runs can print a file the rules were written to keep from the model, and the model then reads that output like any other. The Run Modes page qualifies this for sandboxed commands: inside the sandbox, .cursorignore can hide workspace files from the agent. Cursor's advice is to back the ignore rules with approvals and with file permissions at the OS level.

Platform requirements, network modes, environment variables and the sandbox.json configuration live in the Run Modes sandboxing section, not on the terminal page.

On the network side, there is one list to maintain. The sandbox's default network allowlist is the same set of domains Cloud AgentsAgents that run in a Cursor-managed virtual machine, check out the repo, do the work and open a pull request, then shut down, with no load on your laptop. Press Enter for the full definition. get in Default + allowlist mode, and the team-level allowlist an admin configures applies to both. The Cloud Agent network access page covers what breaks when that list is tightened faster than the host names are known.

Whether the sandbox is a control or a habit depends on who sets it. Cursor's hardening guide tells Enterprise admins to set the org Run Mode policy to Auto-review and enable sandboxing, and that policy holds whoever is at the keyboard. Without it, the sandbox is a per-user default, which works for five people who all know the setting and stops working well short of fifty.

Some shell themes interfere with the inline terminal output, and Cursor names Powerlevel9k and Powerlevel10k as examples. If a command's output looks truncated or misformatted, disable the theme or switch to a simpler prompt while Cursor runs.

Check the command before the theme. Re-run it in a plain shell and compare. If the plain shell shows the same output, the command is the problem, so fix it before you touch your shell config.

You don't have to give up your prompt everywhere. Cursor sets the CURSOR_AGENT environment variable when it is running, so your shell config can detect it and skip the heavy theme only in Cursor sessions. The zsh snippet below does that for Powerlevel10k.

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

The empty branch in that snippet is deliberate. The if body holds only a comment, and the theme loads in the else, so Cursor sessions skip Powerlevel10k while every other shell you open still gets it. Turning the theme off globally would also clear the symptom, but it is a heavier fix than the problem needs, since the only misbehaving session is the one Cursor drives.

The same check works in bash if you would rather fall back to a plain prompt for Cursor sessions than skip a theme.

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

Neither snippet changes what the agent is allowed to run. They change only what the prompt prints.