Cursor recently introduced Background Agents, which can run tasks like code generation, refactoring, and testing in the background. As Background Agents run in the cloud, meaning they need the environment setup for the type of work they will be doing.
For Ruby on Rails apps, we want these agents to have access to Ruby, Node, Yarn, Postgres, Redis, and project-specific dependencies. Without a working environment, results are often incomplete or incorrect.
Here's the approach I used to create a Cursor Base Environment suitable for Rails, ensuring agents can run tests, lint, and build code correctly, just like on your local machine.
All setup files and instructions are available here:
👉 forsbergplustwo/rails-cursor-background-agent-environment
For reference, see the official Cursor Background Agent documentation.
Overview
The setup uses a small collection of scripts placed in your project’s .cursor/ directory to replicate your local environment inside the Cursor Background Agent VM. This includes installing Ruby, Node, Yarn, Postgres, Redis, and any project dependencies defined in your version files.
| File | Purpose |
|---|---|
snapshot.sh |
Installs required system packages (apt) to build Ruby, Node, and gems. Used once to create the base image. |
install.sh |
Installs Ruby, Node, and project dependencies. Seeds the database and prepares the environment. Cached by Cursor. |
start.sh |
Starts Postgres and Redis, checks for dependency changes, and ensures the app is ready to run. |
The environment.json configuration connects these scripts to Cursor’s Background Agent system, defining the snapshot, install, and start commands that initialize your project inside the agent environment.
Why spend time settings this up?
- Background Agents now use the same Ruby and Node versions as your local app
- Tests and build steps run successfully so agents can iterate and validate
- Dependencies are cached between runs for faster startup
- Agents provide consistent results across environments
This makes agent output far more accurate when refactoring, generating code, or running tests in the background.
Usage
Once configured, you can ask your Background Agent to perform tasks like:
-
bin/rails test— Run your test suite -
bin/rails s— Start your Rails server - Refactor or lint code while maintaining project consistency
All environment setup, dependency installation, and database initialization are handled automatically by the scripts.
You can find the full setup guide, scripts, and configuration examples in the open-source repository:
github.com/forsbergplustwo/rails-cursor-background-agent-environment
Pull the repo, copy the scripts into your Rails project, and follow the documented steps to snapshot and start your Background Agent environment.
Contributions and improvements are welcome.
