> ## Documentation Index
> Fetch the complete documentation index at: https://hyperspeed.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Cursor AI

> Back AI staff in chat with Cursor Cloud Agents, giving them access to your codebase through Cursor's AI.

The Cursor integration lets AI staff members in Hyperspeed dispatch tasks to Cursor Cloud Agents. When a chat message is routed to a Cursor-backed service account, Hyperspeed launches a Cursor agent, polls it to completion, and posts the result as a chat reply.

Hyperspeed handles prompt construction, file context, and org key storage. The model inference and agent execution run in Cursor's cloud.

## Setup

<Steps>
  <Step title="Get a Cursor API key">
    Open the [Cursor Dashboard](https://cursor.com/dashboard) and navigate to **Integrations**. Create an API key — keys typically begin with `key_`. Copy it.
  </Step>

  <Step title="Add the key to Workspace Settings">
    In Hyperspeed, open **Workspace Settings → Cursor integration** and paste your API key. Hyperspeed stores it encrypted using `HS_SSH_ENCRYPTION_KEY` (the same 32-byte AES-GCM key used for other workspace secrets).

    <Info>
      You need the `org.manage` permission to configure integrations. Only one Cursor API key can be stored per organization.
    </Info>
  </Step>

  <Step title="Create a Cursor-backed AI staff member">
    Go to **Workspace Settings → AI Staff** and create a service account with:

    * **Provider**: `cursor`
    * **Default repo URL** *(optional)* — the GitHub repository URL to use when a space has no Git link configured (e.g. `https://github.com/your-org/your-repo`).
    * **Default ref** *(optional)* — the branch or commit to check out, e.g. `main`.

    See [AI Staff](/integrations/ai-staff) for full creation steps.
  </Step>
</Steps>

<Note>
  `cursor_default_repo_url` is optional. If unset, Hyperspeed resolves the repository from the space's Git links when launching an agent. If neither is available, the agent launches without a repo context.
</Note>

## Environment variables

These variables configure the Cursor HTTP client on the API server. Set them in your `.env` file or deployment environment.

| Variable | Default | Description |
| - | - | - |
| `CURSOR_API_BASE_URL` | `https://api.cursor.com` | Scheme and host for Cursor API requests. |
| `CURSOR_AGENTS_BASE_URL` | *(empty — falls back to `CURSOR_API_BASE_URL`)* | Origin for Cloud Agents v0 endpoints (`/v0/…`). Set this to override the agents host independently of the base URL. |
| `CURSOR_CHAT_COMPLETIONS_PATH` | `/v1/chat/completions` | Path for OpenAI-compatible completions (used only when pointing at a local bridge, not for Cloud Agents). |
| `CURSOR_COMPLETION_MODEL` | `auto` | Model ID sent in the request body. Use a concrete model ID if `auto` is rejected by your endpoint. |
| `CURSOR_HTTP_AUTH` | `bearer` | Auth scheme: `bearer` sends `Authorization: Bearer <key>`; `basic` sends HTTP Basic with the key as username and an empty password. |

### Cloud Agents v0 authentication

Cursor Cloud Agents v0 uses **HTTP Basic authentication**: the API key as the username with an empty password. Set `CURSOR_HTTP_AUTH=basic` to match this scheme:

```bash theme={null}
CURSOR_HTTP_AUTH=basic
```

Hyperspeed's Cursor-backed chat staff always use `CURSOR_AGENTS_BASE_URL` with the `/v0/agents` path and Basic auth, regardless of `CURSOR_CHAT_COMPLETIONS_PATH`.

<Tip>
  The chat completion env vars (`CURSOR_CHAT_COMPLETIONS_PATH`, `CURSOR_COMPLETION_MODEL`) apply only if you point Hyperspeed at a local OpenAI-compatible bridge that fronts the Cursor CLI. For standard Cloud Agents, only `CURSOR_AGENTS_BASE_URL` and `CURSOR_HTTP_AUTH` matter.
</Tip>

## Agent timeout

The chat AI worker uses a long context timeout (approximately 25 minutes) so Cloud Agent runs have time to poll to completion. You do not need to configure this separately.

## Chat pipeline scope

The Cursor chat pipeline is **read-only** in the current release:

* AI staff can read recent chat messages (`space.chat.read_recent`) and file contents for context.
* `space.file.propose_patch` is not automatically invoked from a Cursor agent run. File proposals require human approval and are deferred to a future release.

<Warning>
  Do not rely on Cursor-backed AI staff to apply code changes automatically. Any file modifications must be proposed and approved by a human member in the workspace UI.
</Warning>

## Self-hosted Cursor worker (optional)

If your team runs Cursor's self-hosted cloud agent worker alongside Hyperspeed:

<Steps>
  <Step title="Install and run the worker">
    Follow [Cursor's self-hosted cloud agents guide](https://cursor.com/blog/self-hosted-cloud-agents) for current install and run instructions. The worker requires outbound HTTPS to Cursor; no inbound exposure is required for worker registration.
  </Step>

  <Step title="Add the worker to your stack">
    Add a `cursor-worker` service to your Docker Compose or Kubernetes deployment alongside the `api`, `web`, Postgres, Redis, and object storage services. Inject the Cursor-provided environment variables for worker identity from Cursor's documentation.
  </Step>

  <Step title="Keep org keys in Hyperspeed">
    The worker is an execution plane only. Org API key storage and space/agent mapping remain in Hyperspeed (API + Postgres). Do not duplicate keys in the worker environment.
  </Step>
</Steps>

## Troubleshooting

**`GET /api/v1/organizations/{orgID}/integrations/cursor` returns `404 page not found`**

The running API binary was built before the Cursor integration routes were added. Rebuild and restart:

```bash theme={null}
docker compose build api && docker compose up -d api
```

**Agent replies with an auth error**

Verify that `CURSOR_HTTP_AUTH=basic` is set and that the API key stored in Workspace Settings is valid. Rotate the key in the Cursor Dashboard if needed, then update it in **Workspace Settings → Cursor integration**.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.