# 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](sandboxes) with [Cursor Cloud Agents](https://cursor.com/docs/cloud-agent/self-hosted/pool) 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:*

1. Accepts a user prompt and sends it to Cursor,
2. Executes the agent's commands in a [Render sandbox](sandboxes), and
3. Copies the resulting output files to the user's machine.

For details, see [How the agent runs](#how-the-agent-runs).

## Prerequisites

Before you start, make sure you have all of the following:

*Render*

- A Render [API key](https://dashboard.render.com/u/settings?add-api-key)
- Your Render workspace ID
    - Obtain this from the top of your workspace's *Settings* page in the [Render Dashboard](https://dashboard.render.com).

*Cursor*

- A Cursor Enterprise plan with [Self-Hosted Machines enabled](https://cursor.com/docs/cloud-agent/self-hosted/pool#prerequisites)
- A [service account API key](https://cursor.com/docs/account/enterprise/service-accounts) with agent scope
- An existing, named [any-repository Team Pool](https://cursor.com/docs/cloud-agent/self-hosted/pool#any-repo-pools)

*Installed tooling*

- Git
- Node.js 22 or later

## Setup

### 1. Clone the template

> *The template code for this tutorial is available on [GitHub](https://github.com/render-examples/cursor-cloud-agent-sandbox).*

Clone the template and install its dependencies:

```shell
git clone https://github.com/render-examples/cursor-cloud-agent-sandbox
cd cursor-cloud-agent-sandbox
npm ci
```

### 2. Configure credentials

1. Copy the example environment file to `.env`:

    ```shell
    cp .env.example .env
    ```

    The file includes the following required environment variables:

    ```bash
    # Render
    RENDER_API_KEY=
    RENDER_WORKSPACE_ID=

    # Cursor
    CURSOR_API_KEY=
    CURSOR_POOL=
    ```

2. Populate the values for these environment variables according to the table below:

| Environment variable | Description |
| --- | --- |
| `RENDER_API_KEY` | Your Render [API key](https://dashboard.render.com/u/settings?add-api-key). Starts with `rnd_` |
| `RENDER_WORKSPACE_ID` | Your Render workspace's ID, available at the top of its *Settings* page in the [Render Dashboard](https://dashboard.render.com). Starts with `tea-` |
| `CURSOR_API_KEY` | Your Cursor [service account API key](https://cursor.com/docs/account/enterprise/service-accounts) 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_POOL` | The name of your [any-repository Team Pool](https://cursor.com/docs/cloud-agent/self-hosted/pool#any-repo-pools), 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:

```shell
npm run agent -- "Create a hello world HTTP server in /workspace/output. Test it before you finish."
```

The agent's activity streams to your terminal, resembling the following:

```
preflight     passed
agent         bc-...
claim         bc-... → pw_render_...
provision     sbx-...
worker        connected
cursor:status RUNNING
cursor:tool   edit_file completed
cursor:tool   run_terminal_cmd completed
cursor:result FINISHED
agent         I created /workspace/output/server.js and confirmed it responds with "Hello, world!".
result        FINISHED (stream)
outputs       copied 1 file to runs/run_.../output
cleanup       Cloud Agent deleted; claim released; sandbox terminated; Team Pool retained
run           runs/run_...
```

In this example:

1. The agent created a web server and tested it inside the sandbox.
2. The runner copied the server to your machine.
3. 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](sandboxes-creating#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 `scripts/install-executor.sh`, and add their download hosts to `INSTALL_DESTINATIONS` in `src/launch-policy.ts`. The template uploads this script to each new sandbox and executes it there before starting Cursor's `agent worker` process. |
| *Network access* | You can customize the sandbox's [network access](sandboxes-creating#network-access) to allow outbound traffic to additional HTTPS destinations. Add the desired hostnames to `RUNTIME_DESTINATIONS` in `src/launch-policy.ts` to include them in the sandbox's allowlist. |
| *Run timeout* | You can set a time limit for the overall agent run, including sandbox setup, task execution, and output collection. Pass `--timeout <seconds>` or set `AGENT_TIMEOUT_SECONDS` (the default is `600`). The runner also derives a separate sandbox lifetime from this value in `src/agent.ts`. |
| *Outputs* | You can choose where generated output files are saved on your machine. Pass `--output ` to specify a local destination directory. The default is `runs/<run_id>/output`. To change which files the template collects from the sandbox, edit `src/outputs.ts`. |

## How the agent runs

The template runs on your local machine. Its [`src/agent.ts`](https://github.com/render-examples/cursor-cloud-agent-sandbox/blob/main/src/agent.ts) coordinates each run through the following stages:

------

##### 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](https://cursor.com/docs/cloud-agent/api/endpoints#claim-a-pending-request) 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 [`src/launch-policy.ts`](https://github.com/render-examples/cursor-cloud-agent-sandbox/blob/main/src/launch-policy.ts).

##### Cursor CLI startup

The template installs a pinned release of Cursor's `agent` CLI inside the sandbox with [`scripts/install-executor.sh`](https://github.com/render-examples/cursor-cloud-agent-sandbox/blob/main/scripts/install-executor.sh), verifying its checksum.

It then writes the session token to a file in the sandbox and starts `agent worker` for that claim. The template confirms that the process is ready and connected to the expected Cloud Agent.

##### Task execution

Cursor runs the agent loop on its infrastructure. When the agent requests a command or file edit, the `agent worker` process executes it inside the sandbox and sends the result back to Cursor.

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 `/workspace/output` in the sandbox to `runs/<run_id>/output` on your machine. It then releases the claim, deletes the Cloud Agent, and terminates the sandbox, keeping your shared Team Pool for future runs.

Cleanup also runs after a failure, a timeout, `Ctrl+C`, or `SIGTERM`. If cleanup fails, follow the instructions under [Troubleshooting](#troubleshooting).

Each run also saves the following files under `runs/<run_id>/`:

- `run.json`: Resource IDs, network policy, and cleanup status, without credentials.
- `events.jsonl`: Run events.
- `result.txt`: The agent's final response.

------

## 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](sandboxes#beta-limitations).*

    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](sandboxes-creating#network-access) is managed via allowlist.*

    The template allows HTTPS traffic to Cursor's [session and artifact hosts](https://cursor.com/docs/cloud-agent/self-hosted/pool#networking), `cursor.com`, and `downloads.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:

```shell
set -a && source .env && set +a
```

The command that terminates a sandbox requires version 2.33.0 or later of the [Render CLI](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.