> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opal.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Cursor Setup

> See and control the tool calls that Cursor's agent makes on your organization's computers.

> [!NOTE]
>
> Tool call governance is currently in limited beta. Contact Opal support to enable it for your organization.

With Cursor connected to [tool call governance](https://docs.opal.dev/docs/tool-call-governance.md), Opal sees every tool call that Cursor's agent makes on your computers, including shell commands, file edits, and MCP calls. Each call appears in Opal on that person's Cursor agent, which comes from your Cursor team sync. Opal can also stop a call before it runs, using your rules. If Opal is slow or can't be reached, the call runs anyway.

To connect your Cursor organization to Opal, so that it syncs your Cursor users and usage, see the [Cursor integration](https://docs.opal.dev/integrations/cursor.md).

## Requirements

Before you begin, you must:

* Be an Opal Admin. Only admins see the **Setup** tab.
* Have Cursor on Mac or Linux computers.
* Have `bash`, `curl`, and `jq` 1.6 or later on each computer. On macOS, `brew install jq` installs jq.
* Make sure each person has an Opal account. They approve a sign-in once, in their browser.
* Decide whether Opal may store conversations. Opal stores none until it turns that on for your organization. See [What Opal records](#what-opal-records).

Each person's calls appear on their Cursor agent. That agent normally comes from your Cursor team sync (see [Cursor Agents](https://docs.opal.dev/docs/agent-inventory-cursor.md)). If a person has none, Opal can create one from their first call when your organization has that turned on. Ask Opal support about it.

In Opal, go to **Agent Center** > **Setup** > **Cursor**. If the page says your Opal doesn't serve the hook kit, contact Opal support.

## Install

### Start with a few people

Each person runs one command in Terminal. To copy it, go to **Agent Center** > **Setup** > **Anthropic** and find the card that starts with "Try it on your own computer". Choose **macOS and Linux** on that card. With your Opal's address in it, the command for Cursor alone is:

```bash theme={null}
curl -fsSL https://<your Opal>/downloads/claude-code-hooks/install.sh | bash -s -- --only=cursor
```

Without `-s -- --only=cursor`, the command also sets up Claude Code, and it sets up Cursor only if the `~/.cursor` folder exists.

1. Run the command. The installer shows what leaves the computer and which files it changes, and asks before it changes anything. Enter `y`.
2. Sign in. The installer shows a code and opens Opal in your browser. Check that the page shows the same code, then approve it. The code lasts 10 minutes. If it expires, the installer stops, and you run it again. Don't approve a code that someone else sent you.
3. Restart Cursor if it was open.

Opal creates a personal access token for the computer, named for what the installer set up, such as **Cursor hooks on** followed by the computer's name. It's listed under **Settings** > **Personal Access Tokens**. Admins see that page. Other people see it only if your organization allows all users to create personal access tokens, and without that setting they can't revoke the token. The token also expires at your organization's maximum API token lifetime, if you set one.

### Roll out to every Mac and Linux computer

Push Cursor's enterprise hooks file with your device management tool, so nobody has to run an installer.

1. In Opal, go to **Agent Center** > **Setup** > **Cursor**. Download `hooks.json`, or fetch it from `https://<your Opal>/downloads/claude-code-hooks/cursor-hooks.json`.
2. Push the file to `/Library/Application Support/Cursor/hooks.json` on macOS, or to `/etc/cursor/hooks.json` on Linux.
3. The first time Cursor runs the hook on a computer, the hook installs Opal's kit in `~/opal-hook/` in the background and opens the Opal sign-in page in the browser. The person approves the code once.

On a computer that gets only this file, every call runs and nothing is sent until the person approves. If a code expires unanswered, the page opens again, at most once an hour, and a day after the person declines.

A computer that also gets Claude Code's managed settings with your organization key signs in once. Until the person approves, calls are sent with that key and the person's email. If someone also ran the installer by hand, each call is still reported once.

## Check that it works

1. In Cursor, ask the agent to run `echo opal-check`.
2. In Opal, go to **Agent Center** > **Activity**. Within a few seconds, the call appears on the person's Cursor agent.
3. To test a block, make sure **Enforce** is on for Cursor under **Setup** > **Clients**. Create a rule that blocks Cursor calls with arguments matching `*opal-block-test*`, then ask the agent to run `echo opal-block-test`. If Opal enforces rules for your organization, Cursor shows Opal's reason and doesn't run the call. If it doesn't yet, the call runs, and **Activity** shows **Would have blocked** on it. Contact Opal support to turn on enforcement. Delete the rule afterwards. For how to create a rule, see [Create a rule](https://docs.opal.dev/docs/tool-call-governance-rules.md#create-a-rule).

If the call doesn't appear, check the following:

| What you see | What it means | What to do |
| - | - | - |
| Nothing in **Activity** | On a computer set up through the hooks file, the person hasn't approved the sign-in. Until they do, calls run and nothing is sent. | Ask them to approve the code in their browser. |
| Nothing in **Activity** | Cursor's **Log** and **Enforce** switches are both off. | Turn one on under **Setup** > **Clients**. |
| Nothing in **Activity**, and no errors in `errors.log` | Tool call governance isn't turned on for your organization. Opal accepts what computers send and doesn't store it. | Contact Opal support. |
| The call shows under an email, or as **Unknown agent** | The person has no Cursor agent in Opal, and your organization hasn't turned on creating agents from calls. | Connect your Cursor organization so each person has an agent, or ask Opal support to turn on creating agents from calls. |
| `status=401` in `~/opal-hook/errors.log` | Opal refused the token. | Check whether the token expired or was revoked. |
| `status=curl-error-7` in `~/opal-hook/errors.log` | The computer couldn't connect to Opal. | Check that the computer can reach your Opal's address. |

## What Opal records

For every call, whatever your conversation setting is, Opal receives:

* The tool's name and arguments, for example the shell command. Arguments are sent as they are, so a secret pasted into a command reaches Opal. Opal masks credentials and personal data, such as email addresses and phone numbers, in the copy it stores. Your rules match the arguments as sent.
* For an MCP call, the server's name and URL, or a hash of its command.
* Who the person is, as labels: the email set at install, which is their Opal account's email unless you gave another, the email of the account Cursor is signed in with, their git email, their user name on the computer, and the computer's name. If a person signed in to Cursor with a personal account, that address is sent.
* The time of the call.

Opal doesn't receive the model's thinking or Cursor's transcript file.

Opal turns on conversation content storage for each organization. Until it is on for yours, Opal stores none, whatever you choose in **Clients**. Contact Opal support to turn it on. After that, **Store conversation content** decides for each client. Go to **Agent Center** > **Setup** > **Clients**, find Cursor, and set it:

| Choice | What happens |
| - | - |
| Always (the default) | Every computer sends the conversation, and Opal stores it. |
| Each person decides | A computer sends it only if its person installed with `--content`, and Opal stores what it receives. |
| Never | Opal stores none, even if a computer was installed with `--content`. |

When the conversation is sent, Opal gets each prompt, each reply the model writes, and what each tool printed. Opal masks credentials and personal data in the text and cuts long text to a size limit. These settings apply to your whole organization, and computers pick up a change within a few minutes without a reinstall.

Admins and read-only admins can see all of this, on the agent's **Activity** tab. Auditors and other users can't.

## What isn't covered

* **Cursor's cloud agents** don't run the hooks on your computers. Contact Opal support for the cloud agent setup.
* **Windows** isn't supported yet.
* **Secrets in prompts.** Opal checks Claude Code prompts for secrets and can block them. It doesn't check Cursor prompts.
* **Rules that ask the developer to confirm.** Cursor can't ask, so it refuses a call that such a rule matches, with a message that says so.

## Turn it off or remove it

* **Switch Cursor off for everyone.** Under **Agent Center** > **Setup** > **Clients**, turn **Log** and **Enforce** off for Cursor. A client with both off sends nothing, and its tool calls run without Opal's check. Computers notice within a few minutes, with no reinstall.
* **Remove it from one computer.** Run `bash ~/opal-hook/uninstall.sh`, then restart Cursor. It removes Opal's entries from `~/.cursor/hooks.json` after saving a backup, and deletes `~/opal-hook/`. It also removes Opal's Claude Code hook from the same computer, because the two share one kit. It doesn't revoke the token. To revoke it, use **Settings** > **Personal Access Tokens**, which admins see, and other people see only if your organization allows all users to create personal access tokens.
* **Remove the rollout.** Take the hooks file off the computers with your device management tool. The kit's files stay in `~/opal-hook/` until you run the uninstall command on each computer.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.