Cursor Cloud Agents with Render Sandboxes
Give Cursor an isolated execution environment in your Render workspace.
Render Sandboxes is in public beta.
APIs, defaults, and limits might change during the beta period.
You can use Render Sandboxes with Cursor Cloud Agents to integrate Cursor's core agent loop with isolated, self-hosted code execution in your Render workspace. Cursor hosts the loop as usual, while the sandbox executes the agent's commands and file edits.
This tutorial walks through running a basic coding agent that:
- Accepts a user prompt and sends it to Cursor,
- Executes the agent's commands in a Render sandbox, and
- Copies the resulting output files to the user's machine.
For details, see How the agent runs.
Prerequisites
Before you start, make sure you have all of the following:
Render
- A Render API key
- Your Render workspace ID
- Obtain this from the top of your workspace's Settings page in the Render Dashboard.
Cursor
- A Cursor Enterprise plan with Self-Hosted Machines enabled
- A service account API key with agent scope
- An existing, named any-repository Team Pool
Installed tooling
- Git
- Node.js 22 or later
Setup
1. Clone the template
The template code for this tutorial is available on GitHub.
Clone the template and install its dependencies:
2. Configure credentials
-
Copy the example environment file to
.env:The file includes the following required environment variables:
-
Populate the values for these environment variables according to the table below:
Environment variable Description RENDER_API_KEYYour Render API key.
Starts with
rnd_RENDER_WORKSPACE_IDYour Render workspace's ID, available at the top of its Settings page in the Render Dashboard.
Starts with
tea-CURSOR_API_KEYYour Cursor service account API key with agent scope.
The template uses this key locally to manage your Cloud Agent and its pool claim. It is not passed into the sandbox.
CURSOR_POOLThe name of your any-repository Team Pool, such as
my-pool.
3. Perform your first agent run
This example handles one prompt per run and does not support follow-up messages. Provide a task the agent can complete without additional input.
Make sure no other process can claim work from your pool, then run the agent with a prompt:
The agent's activity streams to your terminal, resembling the following:
In this example:
- The agent created a web server and tested it inside the sandbox.
- The runner copied the server to your machine.
- The runner released the claim, deleted the Cloud Agent, and terminated the sandbox to clean up.
4. Customize agent capabilities (optional)
These customization methods are specific to this template.
For general-purpose customization of Render Sandboxes, see Configuring sandbox behavior.
| Customization | Description |
|---|---|
|
Toolchain |
You can install additional command-line tools for the agent to use inside the sandbox. Add installation commands to The template uploads this script to each new sandbox and executes it there before starting Cursor's |
|
Network access |
You can customize the sandbox's network access to allow outbound traffic to additional HTTPS destinations. Add the desired hostnames to |
|
Run timeout |
You can set a time limit for the overall agent run, including sandbox setup, task execution, and output collection. Pass The runner also derives a separate sandbox lifetime from this value in |
|
Outputs |
You can choose where generated output files are saved on your machine. Pass To change which files the template collects from the sandbox, edit |
How the agent runs
The template runs on your local machine. Its src/agent.ts coordinates each run through the following stages:
| Stage | Description |
|---|---|
|
Agent creation and claim |
From your local machine, the template checks that the configured Team Pool exists and isn't tied to a repository. It then calls the Cursor API to create a Cloud Agent with your prompt, targeting that pool. The template claims the agent's queued work for this run's sandbox, reserving it so another process can't take it. Cursor returns a session token that can serve only that claim. |
|
Sandbox creation |
The template creates a Render sandbox and waits until it's running. Its network policy and environment variables are defined in |
|
Cursor CLI startup |
The template installs a pinned release of Cursor's It then writes the session token to a file in the sandbox and starts |
|
Task execution |
Cursor runs the agent loop on its infrastructure. When the agent requests a command or file edit, the The template streams run events and the agent's response to your terminal. |
|
File collection and cleanup |
When the run finishes successfully, the template downloads regular files from Cleanup also runs after a failure, a timeout, Each run also saves the following files under
|
Security considerations
-
Your Cursor API key never enters the sandbox.
Any code that the agent executes in the sandbox can read the session token and any other credentials you place there. Make sure that any values you set are safe to expose.
Use a dedicated Team Pool with no other processes waiting to claim work. Otherwise, another process could receive your run and execute its commands outside the intended sandbox.
-
Credential brokering for Render Sandboxes is not yet generally available.
The template currently writes the session token to a file in the sandbox. This behavior is defined entirely in
src/launch-policy.ts. -
Sandbox network access is managed via allowlist.
The template allows HTTPS traffic to Cursor's session and artifact hosts,
cursor.com, anddownloads.cursor.com. The download host remains allowed throughout the run, even after installation finishes.Tool inputs and outputs pass through Cursor, because Cursor hosts the agent loop.
Troubleshooting
Preflight fails.
Confirm that Self-Hosted Machines is enabled, that the pool name is correct, that the pool is an any-repository pool, and that the service account key has agent scope.
The pool request is never claimed.
Confirm that the request targets the configured pool and that another process hasn't claimed it first.
The worker never becomes ready.
Check the [worker:stderr] lines, the session token, and the sandbox's network access. The process must report ready at /readyz, and Cursor must show it connected to the expected Cloud Agent.
The agent produces no output files.
Inspect runs/<run_id>/events.jsonl and result.txt. Output files are optional, so prompts that need files should ask the agent to write them under /workspace/output.
Cleanup is incomplete.
If a cleanup step fails, the runner prints the commands that finish it, with the resource IDs filled in. Release the claim, delete the per-run Cloud Agent, and terminate the sandbox, but keep the shared Team Pool.
The commands read your credentials from your shell, so load .env from the template directory before you run them:
The command that terminates a sandbox requires version 2.33.0 or later of the Render CLI.
If Cloud Agent creation fails without a clear answer from the API, the runner also prints a reconcile command that lists recent Cloud Agents, so you can find and permanently delete one that might have been created.