With background agents, you can spawn off asynchronous agents that can edit and run your code in a remote environment. At any point, you can view their status, send a follow-up, or take over.

​
How to Use

  1. Hit to open up the backgound agent control panel which allows you to list your agents, spawn new ones, and view their status.
  2. Once you have submitted a prompt, select your agent from the list to view the status and enter the machine the agent is running in.

To function, background agents require data retention on the order of a few days.

​
Feedback

We’d love your direct feedback in our Discord #background-agent channel or via email to background-agent-feedback@cursor.com. Please send us bugs, feature requests or ideas.

​
Setup

The background agent by default runs in an isolated machine which is set up with an ubuntu-based image. The background agent has access to the internet and can install packages required to run your app.

​
GitHub connection

Background agents currently clone your repo from GitHub. They also do their work on a separate branch and push to your repo to make it easy for you to take over from them.

This means you need to grant read-write privileges to your repo (and any dependent repos or submodules). In the future, we will also support other providers (GitLab, BitBucket, etc).

​
Base Environment Setup

For more advanced cases, you can set up the environment yourself. You’ll get an IDE instance connected to the remote machine. Set up your machine, install development tools and packages, then take a snapshot once everything looks good. Next, configure the runtime settings:

  • The install command runs before an agent starts and should install runtime dependencies. This might mean running npm install or bazel build.
  • Terminals let you run background processes while the agent is working - like spinning up a web server or compiling protobuf files.

For the most advanced use cases, you can also use a Dockerfile for machine setup. The dockerfile lets you declaratively set up system-level dependencies: install specific versions of compilers, debuggers, or even switch out the base OS image completely. Note that the dockerfile shouldn’t COPY the entire project - we manage the workspace and will check out the correct commit. Like the snapshot-based setup, you’ll still need to handle dependency installation in the install script.

If you need to enter any required secrets for running your dev environment, and they will be stored encrypted-at-rest (using KMS) in our database and provided in the background agent environment.

The machine setup lives in a .cursor/environment.json file, which can be committed in your repo (recommended) or stored privately for your user. The setup flow will guide you through creating a proper environment.json file.

​
Maintenance Commands

When setting up a new machine for a new background agent, we start from the base environent, and then run the install command that’s configured in your environment.json file. This command can be thought of as the command that a developer would need to run when switching branches. In particular, it should install any dependencies that may be new.

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

To ensure that machine startup is fast, we cache the disk state after the install command is run. This means that it should be designed to be run many times over. Only the disk state is persisted from the install command, so any processes started here will not be alive when the agent starts.

​
Startup Commands

After running the install command, the machine is started, and we will run the start command followed by starting any terminals. This allows you to start processes that should be alive when the agent is running.

The start command can often be skipped. One common case where you want to use it is if your dev environment relies on docker, in which case you would want to put sudo service docker start in the start command.

The terminals are meant for your app code. These terminals will run in a tmux session that is available both to you and the agent. For example, many website repos will put npm run watch as one of the terminals.

​
The environment.json Spec

Informally, the environment.json file can look like the following:

{
  "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 to use for background agents. Pricing is based on token usage. Eventually, we may also start charging for the dev environment compute.

​
Security

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

Here’s what you should know about the feature:

  1. You will need to grant read-write privileges to our GitHub app to the repos you want to edit with background agent. We use this to clone the repo and make changes for you.
  2. Your code will run inside our AWS infrastructure in isolated VMs, and will be stored on the VM disks as long as the agent is accessible.
  3. The agent has access to the internet.
  4. The agent auto-runs all terminal commands, which allows it to be useful by iterating on tests. This is different from the foreground agent, which by default requires user approval for every command. Auto-running introduces a data exfiltration risk: it is quite possible for an attacker to execute a prompt injection attack, tricking the agent to upload code to a malicious website. For example, see this explanation by OpenAI about the risks of prompt injection for background agents.
  5. If you have not enabled privacy mode, we collect prompts and dev environments and store them to help improve the product.
  6. If you have privacy mode disabled when starting a background agent, then enable privacy mode during the agent’s run, the agent will continue operating with privacy mode disabled until it completes.