Is this page helpful?

Use Cursor with AI Workbench#

Overview#

The Cursor integration streamlines attaching Cursor to a project container.

Adding Cursor to a project puts a Cursor option in the Application Launcher dropdown. Launching Cursor starts the project container and attaches a Cursor window to the container, regardless of whether it’s local or remote.

AI Workbench creates .cursor/rules/ai-workbench in the repository with preconfigured MDC rules.

These rules make Cursor aware of AI Workbench features and conventions without additional configuration. You can add your own rules to tell the agent about constraints, file structure and operations that require a rebuild.

The integration sets up the IDE connection but does not configure agent sandboxing.

Cursor’s agent sandboxing (sandbox.json, hooks.json) is separate from the Workbench integration. If you want agent-level controls beyond the container boundary, you configure those yourself. See Agent Sandboxing in Containers for what works and what doesn’t.

Launching Cursor in a project container is different for remote only mode.

The current integration uses a container runtime to setup a socket for Cursor to access the container. This works in full local mode because there’s an installed container runtime but can fail for remote only mode.

This will be addressed in a future release. Follow the Manual Steps section below for remote only mode.

Prerequisites: Full Local Install#

For the integration to work out of the box, you must have done the following steps.

  1. Install AI Workbench in full local mode. See here <full-local-install>.

  2. Install the Cursor desktop application. Go to the Cursor site and download the version for your operating system.

Add Cursor to a Project#

Step One: Open the project that you want to add Cursor to.

  1. Select Locations Manager > Location Card > Project Card

Step Two: Add Cursor to the project.

  1. Select Project Tab > Project Container > Apps (LHS) > Add

  2. Select Cursor

Success: The modal disappears and the Application Launcher shows Cursor in the drop down.

Open Cursor in a Project#

Once Cursor is added to the project, open it using the Application Launcher.

This will work for local projects and remote projects.

  1. Select Project Tab > Application Launcher > Cursor

  2. Wait for the project container to start and the Cursor server to be installed

    1. There is a timeout on the application launch, so you may see an error message if it takes a while install the Cursor server

    2. You can dismiss the error message and the Cursor window will open once the server is installed

  3. Then use Cursor normally.

Manual Steps: Remote Only Mode#

Use this process if you have the Desktop App in remote only mode.

Step One: Install Cursor locally.

See above.

Step Two: Add Cursor to the project.

See above.

Step Three: Start the Project container.

  1. Select Project Tab > Project Dashboard > Project Container > Start

  2. Wait for the project container to start

Step Four: Open Cursor and connect it to the remote.

  1. Open a new Cursor window > Select Connect via SSH

  2. Select the location name or IP from the options provided in the top search bar

  3. Wait for the connection to be made

Step Five: Connect Cursor to the running project container.

  1. Then go to Search Bar (Top) > Dev Containers: Attach to a Running Container

  2. Hit Enter and Select Drop Down > Select the container name > Hit Enter

Step Six: Open the project.

  1. Select Cursor window > Open Folder (LHS)

  2. Locate the project folder and select it

Agent Sandboxing in Containers#

The project container is the primary sandbox for Cursor’s agent.

Cursor’s built-in OS-level sandbox relies on kernel features (Landlock, seccomp) and an AppArmor profile that may not be available or functional inside a container. When prerequisites are not met, Cursor silently falls back to unsandboxed execution with no warning. The container boundary, where the agent runs as workbench without sudo, is the enforcement layer you can rely on.

Hooks are the strongest Cursor-specific control available in a container.

The Cursor server spawns hook scripts as child processes inside the container. Project-level hooks (<workspace>/.cursor/hooks.json) run from the project root. User-level hooks (~/.cursor/hooks.json) run from the ~/.cursor/ directory inside the container.

Known issue with hook permissions.

Hooks that return "permission": "ask" are not enforced — the agent proceeds without waiting for approval. Only "deny" (exit code 2) reliably blocks an action. Use exit code 2 for anything that must be stopped.

sandbox.json filesystem restrictions may provide additional protection but are not guaranteed.

The Cursor server reads sandbox.json from inside the container. If the host kernel supports Landlock v3 (kernel 6.2+) and the container runtime allows the required syscalls, filesystem deny lists will be enforced. If not, the restrictions silently do not apply.

MDC rules inform the agent but do not enforce anything.

AI Workbench populates initial rules in .cursor/rules/ai-workbench/ automatically. You can add your own .mdc files to tell the agent about operations that require a rebuild, files it should not modify, and available tools. The agent can ignore rules. For constraints that must be enforced, use hooks.

permissions.json reduces approval prompts but does not add security.

Place it at ~/.cursor/permissions.json inside the container to auto-allow safe commands like git status or npm test. It has no per-project override — it is a convenience feature for reducing approval prompts, not a security boundary.

Cursor Sandbox Limitations in Containers#

Cursor’s OS-level sandbox silently falls back to unsandboxed execution when prerequisites are not met.

There is no warning in the Cursor UI. Failures are only logged in remoteexthost.log. You cannot assume the sandbox is active unless you have verified the prerequisites.

The sandbox requires kernel and runtime support that containers may not provide.

Landlock v3 requires the host kernel to be 6.2 or later with CONFIG_SECURITY_LANDLOCK=y. Unprivileged user namespaces must be enabled, which Docker restricts by default. The cursor-sandbox-remote AppArmor profile must be manually installed inside the container — it does not ship with remote or CLI installations.

The shipped AppArmor profile has known issues on Ubuntu 24.04 and later.

It is missing the ABI 4.0 declaration and network rules required by newer AppArmor versions. This causes the sandbox preflight check to fail, triggering the silent fallback.

The sandbox does not protect against terminal access to ignored files.

Files listed in .cursorignore are hidden from Cursor’s file-read tool but not from shell commands. The agent can still cat any file that the filesystem sandbox allows.

UID remapping can break container tooling.

The sandbox remaps processes internally, causing $(id -u) to return incorrect values. Use the CURSOR_ORIG_UID and CURSOR_ORIG_GID environment variables instead if your hooks or scripts need the real user identity.

Rely on the container boundary as your primary enforcement layer.

The agent runs as workbench without sudo. It cannot install system packages, modify system files or access the host filesystem outside the mounted project directory. Layer hooks and rules on top for command filtering and agent guidance. Treat sandbox.json as optional hardening, not a guarantee.