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

# Cursor

> Configure coding-agent connections and select the provider backend Genesis uses for coding tasks.

## Overview

Cursor appears in **Config -> Connections** under the **Dev Tools** category.
Genesis uses a shared-scope **API Key** connection to authenticate with Cursor
Cloud when the enhancement coding-agent launcher runs in **cloud** mode.

After setup, Genesis tests the connection by calling `GET /v1/models` on the
configured API base URL (default `https://api.cursor.com`).

<Tip>
  The Cursor connection powers the cloud adapter for
  [Support and Enhancements](/docs/Setup/Support-And-Enhancements#cursor-control-center).
  Pair it with `genesis_enhancements.cursor_agent.*` settings in
  [Advanced Settings](/docs/Setup/Advanced-Settings) or `genesis-config.yaml`.
</Tip>

## Setup workflow

<Steps>
  <Step title="Open the Cursor connector">
    Go to **Config -> Connections**, choose **Dev Tools**, then select **Cursor**.
  </Step>

  <Step title="Create a shared connection">
    Save the connection with **Shared** scope. The cloud adapter rejects
    personal-scope Cursor connections.
  </Step>

  <Step title="Enter API credentials">
    Paste a Cursor enterprise service-account API key. Override **API Base URL**
    only when testing against a non-production endpoint.
  </Step>

  <Step title="Test and save">
    Run the built-in connection test, verify the success message, then save the
    connection. Record the connection name — you reference it from
    `genesis_enhancements.cursor_agent.connection_name`.
  </Step>

  <Step title="Enable the cloud launcher">
    In **Advanced Settings** or `genesis-config.yaml`, set
    `genesis_enhancements.cursor_agent.enabled` to `true`,
    `genesis_enhancements.cursor_agent.adapter` to `cloud` (or `auto` when no
    local runner command is configured), `genesis_enhancements.cursor_agent.connection_name`
    to the saved connection name, and `genesis_enhancements.cursor_agent.target_repo_url`
    to the GitHub repository Cursor agents should modify.
  </Step>
</Steps>

<Note>
  If your deployment uses outbound allowlists or external access controls,
  allow Genesis to reach `api.cursor.com` (or your configured API base URL).
</Note>

## Connection fields

### `api_key`

| **Field** | **Type** | **Required** | **Default** | **Notes** |
| - | - | - | - | - |
| **`api_key`** | String | Yes | none | Cursor enterprise service-account API key. Stored as a secret. |
| **`api_base_url`** | String | No | `https://api.cursor.com` | Override only for testing or dedicated endpoints. |

## Launcher settings that use this connection

Configure these `genesis_enhancements.cursor_agent` fields alongside the
connection:

| Setting | Type | Default | Description |
| - | - | - | - |
| `enabled` | boolean | `false` | Enable the coding-agent launcher. Honors `CURSOR_AGENT_TICKET_ENABLED` when unset. |
| `adapter` | string | `auto` | `auto`, `local`, or `cloud`. `auto` picks a local runner when `CURSOR_AGENT_RUNNER_COMMAND` is set; otherwise cloud when `connection_name` is set. Explicit `cloud` overrides a configured local runner. |
| `connection_name` | string | `""` | Name of the shared-scope Cursor connection used by the cloud adapter. |
| `target_repo_url` | string | `""` | GitHub repository URL cloud agents work on. Required for cloud runs. |
| `target_base_ref` | string | `main` | Base ref cloud agents start from. Honors `CURSOR_AGENT_TARGET_BRANCH` when unset. |
| `auto_create_pr` | boolean | `true` | Ask Cursor Cloud to open a pull request automatically on completion. |

## What it enables

When the cloud adapter is configured, Genesis can:

* launch Cursor Cloud agents from the **Software Factory** page and from
  enhancement reports on **Support and Enhancements**,
* poll agent status, branch name, pull request URL, and agent URL through the
  Cursor Cloud API,
* start agent runs from `genesis_enhancement_action` with
  `START_CURSOR_AGENT` and inspect them with `GET_CURSOR_AGENT_STATUS`.

Local runner mode (`adapter: local` or `auto` with `CURSOR_AGENT_RUNNER_COMMAND`
set) does not use this connection.

## Claude Code backend

Genesis can run the same coding-agent workflow through Claude Code instead of
Cursor Cloud. Select the provider-neutral backend with
`genesis_enhancements.coding_agent.backend: claude_code` and enable it with
`genesis_enhancements.coding_agent.claude_code.enabled: true`. The Claude Code
backend clones `genesis_enhancements.coding_agent.claude_code.target_repo_url`,
cuts each run's worktree from `target_base_ref` (default `main`), and uses the
configured `connection_name` for the model credential. Configure
`git_connection_name` separately for the GitHub App identity that pushes the
branch and opens the pull request.

Claude Code runs locally in a child process with a per-run worktree. Their run
evidence is persisted under the run root, while the default worktree directory
(`worktree_root: /opt/genesis-agents-start-cursor-agent`) is ephemeral on EKS.
See [Advanced Settings](/docs/Setup/Advanced-Settings#provider-neutral-coding-agent-backend)
for all Claude Code limits and timeouts, and [Connections](/docs/Setup/Connections#claude-code-connections)
for the supported credential profiles.

## Related pages

* [Connections](/docs/Setup/Connections)
* [Support and Enhancements](/docs/Setup/Support-And-Enhancements)
* [Advanced Settings](/docs/Setup/Advanced-Settings)
* [Genesis enhancement tools](/docs/Genbot-Toolkit/Additional-Tool-Groups#genesis-enhancement-tools)