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

1. Get a Cursor API key

   Open the Cursor Dashboard and navigate to Integrations. Create an API key — keys typically begin with key_. Copy it.

2. 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).

   You need the org.manage permission to configure integrations. Only one Cursor API key can be stored per organization.

3. 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 for full creation steps.

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.

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:

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.

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.

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.

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.

Self-hosted Cursor worker (optional)

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

1. Install and run the worker

   Follow Cursor’s self-hosted cloud agents guide for current install and run instructions. The worker requires outbound HTTPS to Cursor; no inbound exposure is required for worker registration.

2. 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.

3. 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.

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:

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.