Asynchronous remote agents in Cursor
Background agents require data retention on the order of a few days.
npm install
or bazel build
.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
.
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.
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
Specenvironment.json
file can look like: