Asynchronous remote agents in Cursor
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.
Background agents require data retention on the order of a few days.
Send feedback to our Discord #background-agent channel or background-agent-feedback@cursor.com. Please send bugs, feature requests or ideas.
Background agents run in an isolated ubuntu-based machine by default. Agents have internet access and can install packages.
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.
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:
npm install
or bazel build
.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
.
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.
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.
environment.json
SpecThe environment.json
file can look like:
Formally, the spec is defined here.
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.
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:
Asynchronous remote agents in Cursor
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.
Background agents require data retention on the order of a few days.
Send feedback to our Discord #background-agent channel or background-agent-feedback@cursor.com. Please send bugs, feature requests or ideas.
Background agents run in an isolated ubuntu-based machine by default. Agents have internet access and can install packages.
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.
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:
npm install
or bazel build
.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
.
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.
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.
environment.json
SpecThe environment.json
file can look like:
Formally, the spec is defined here.
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.
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: