With background agents, spawn asynchronous agents that edit and run code in a remote environment. View their status, send follow-ups, or take over anytime.

​
How to Use

  1. Hit to open the background agent control panel to list agents, spawn new ones, and view status.
  2. After submitting a prompt, select your agent from the list to view status and enter the machine.

Background agents require data retention on the order of a few days.

​
Feedback

Send feedback to our Discord #background-agent channel or background-agent-feedback@cursor.com. Please send bugs, feature requests or ideas.

​
Setup

Background agents run in an isolated ubuntu-based machine by default. Agents have internet access and can install packages.

​
GitHub connection

Background agents clone your repo from GitHub and work on a separate branch, pushing to your repo for easy handoff.

Grant read-write privileges to your repo (and any dependent repos or submodules). We’ll support other providers (GitLab, BitBucket, etc) in the future.

​
Base Environment Setup

For advanced cases, set up the environment yourself. Get an IDE instance connected to the remote machine. Set up your machine, install tools and packages, then take a snapshot. Configure runtime settings:

  • Install command runs before an agent starts and installs runtime dependencies. This might mean running npm install or bazel build.
  • Terminals run background processes while the agent works - like starting a web server or compiling protobuf files.

For the most advanced cases, use a Dockerfile for machine setup. The dockerfile lets you set up system-level dependencies: install specific compiler versions, debuggers, or switch the base OS image. Don’t COPY the entire project - we manage the workspace and check out the correct commit. Still handle dependency installation in the install script.

Enter any required secrets for your dev environment - they’re stored encrypted-at-rest (using KMS) in our database and provided in the background agent environment.

The machine setup lives in .cursor/environment.json, which can be committed in your repo (recommended) or stored privately. The setup flow guides you through creating environment.json.

​
Maintenance Commands

When setting up a new machine, we start from the base environment, then run the install command from your environment.json. This command is what a developer would run when switching branches - install any new dependencies.

For most people, the install command is npm install or bazel build.

To ensure fast machine startup, we cache disk state after the install command runs. Design it to run multiple times. Only disk state persists from the install command - processes started here won’t be alive when the agent starts.

​
Startup Commands

After running install, the machine starts and we run the start command followed by starting any terminals. This starts processes that should be alive when the agent runs.

The start command can often be skipped. Use it if your dev environment relies on docker - put sudo service docker start in the start command.

terminals are for app code. These terminals run in a tmux session available to you and the agent. For example, many website repos put npm run watch as a terminal.

​
The environment.json Spec

The environment.json file can look like:

{
  "snapshot": "POPULATED_FROM_SETTINGS",
  "install": "npm install",
  "terminals": [
    {
      "name": "Run Next.js",
      "command": "npm run dev"
    }
  ]
}

Formally, the spec is defined here.

​
Models

Only Max Mode-compatible models are available for background agents and only available with usage based pricing. Pricing is based on token usage. We may also charge for dev environment compute.

​
Security

Background Agents are available in Privacy Mode. We never train on your code and only retain code for running the agent. Learn more about Privacy mode

What you should know:

  1. Grant read-write privileges to our GitHub app for repos you want to edit. We use this to clone the repo and make changes.
  2. Your code runs inside our AWS infrastructure in isolated VMs and is stored on VM disks while the agent is accessible.
  3. The agent has internet access.
  4. The agent auto-runs all terminal commands, letting it iterate on tests. This differs from the foreground agent, which requires user approval for every command. Auto-running introduces data exfiltration risk: attackers could execute prompt injection attacks, tricking the agent to upload code to malicious websites. See OpenAI’s explanation about risks of prompt injection for background agents.
  5. If privacy mode is disabled, we collect prompts and dev environments to improve the product.
  6. If you disable privacy mode when starting a background agent, then enable it during the agent’s run, the agent continues with privacy mode disabled until it completes.