> For the complete documentation index, see [llms.txt](https://docs.sonarsource.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sonarsource.com/sonarqube-server/instance-administration/ai-features/sonar-vortex.md).

# Sonar Vortex

License, deploy, and enable Sonar Vortex on SonarQube Server so your developers' coding agents can use Guide and Verify.

Sonar Vortex equips a coding agent to write code that fits your project, and to check that code as it is produced. On SonarQube Server, it works with:

* Coding agents, for example Claude Code, Codex, or Cursor, reached through the SonarQube CLI connected to your instance, a SonarQube agent plugin, or a locally running SonarQube MCP Server
* The Remediation Agent, which uses Vortex analysis to verify its own fix suggestions, see [#vortex-and-the-remediation-agent](#vortex-and-the-remediation-agent "mention")

This page covers what you do as an administrator to make Vortex available. To learn how Vortex context and Vortex analysis work, see [What is Sonar Vortex?](/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex.md) in the Agent Centric Development Cycle documentation. For subscription and consumption details, see [#subscription-and-consumption](#subscription-and-consumption "mention").

## Subscription and consumption <a href="#subscription-and-consumption" id="subscription-and-consumption"></a>

### Subscription requirements <a href="#subscription-requirements" id="subscription-requirements"></a>

Vortex requires a separate subscription alongside your SonarQube Server Enterprise or Data Center edition. See the [Sonar product subscriptions](/sonarqube-server/instance-administration/license-management/product-subscriptions.md) page for details about adding a subscription. Your SonarQube Server license must be activated through LicenseSpring, either online or offline; Vortex is not available with a server ID-based license.

Your Vortex subscription supports overage, letting your coding agents keep using Vortex past your base allowance for an extra monthly cap you set yourself. See the [Overage activation](/sonarqube-server/instance-administration/license-management/overage-activation.md) page to activate it. Overage requires online license connectivity and is not available on a server ID-based license. Your base allowance and overage cap are both measured in tool calls.

### What counts as a tool call <a href="#what-counts-as-a-tool-call" id="what-counts-as-a-tool-call"></a>

A tool call is the unit Vortex consumes each time a coding agent uses one of its tools, for example retrieving the current architecture or analyzing one or more files. Tool calls are drawn from your base allowance first and, if overage is active, from your overage cap. The number of tool calls for a given task depends on:

* The size of the codebase
* The type and difficulty of the task
* The specific coding agent used

See the [Sonar product subscriptions](/sonarqube-server/instance-administration/license-management/product-subscriptions.md) page to manage your tool call usage.

## Vortex and SonarQube Server's Remediation Agent <a href="#vortex-and-the-remediation-agent" id="vortex-and-the-remediation-agent"></a>

The Remediation Agent's use of Vortex analysis to verify its own fix suggestions does not require a Vortex subscription, a Vortex license, or the Vortex setting turned on. A Vortex subscription is required only when using Vortex with your own coding agents, reached through the SonarQube CLI, a SonarQube agent plugin, or a locally running SonarQube MCP Server, see [#vortex-with-your-own-coding-agent](#vortex-with-your-own-coding-agent "mention").

Deploying the Remediation Agent always deploys the Vortex analysis component it depends on. This is because the Remediation Agent uses Vortex analysis to verify its fix suggestions, even if you do not have a Vortex subscription. There is no separate Vortex setup for the Remediation Agent: follow its own setup overview, prerequisites, and enabling steps in [Remediation Agent](/sonarqube-server/instance-administration/ai-features/remediation-agent.md).

## Vortex with your own coding agent <a href="#vortex-with-your-own-coding-agent" id="vortex-with-your-own-coding-agent"></a>

Making Vortex available to your developers' own coding agents, for example Claude Code, Codex, or Cursor, takes more setup than the Remediation Agent: a license, a deployed Vortex analysis component, and the Vortex setting turned on.

### Setup overview <a href="#setup-overview" id="setup-overview"></a>

Setup spans several roles. Complete the steps in order.

| Step | Task                                                            | Who does it            | Where                                                                                                                |
| ---- | --------------------------------------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------- |
| 1    | Add Vortex to your license                                      | Instance administrator | [Sonar product subscriptions](/sonarqube-server/instance-administration/license-management/product-subscriptions.md) |
| 2    | Deploy the Vortex analysis component on your own infrastructure | System administrator   | [Installation overview](/sonarqube-server/server-installation/ai-agents/installation-overview.md#vortex-analysis)    |
| 3    | Enable Vortex                                                   | Instance administrator | [#enabling-vortex](#enabling-vortex "mention")                                                                       |

### Prerequisites <a href="#prerequisites" id="prerequisites"></a>

* The Vortex analysis component is deployed alongside SonarQube Server, with shared storage and a signing key. See [Installation overview](/sonarqube-server/server-installation/ai-agents/installation-overview.md#vortex-analysis)
* Each project, and the branches your developers work from, have been analyzed in your CI pipeline, so Vortex has analyzer context to restore
* Your reverse proxy or ingress allows a request body large enough for analyzer context uploads. See [Installation overview](/sonarqube-server/server-installation/ai-agents/installation-overview.md#reverse-proxy-body-size)

### Enabling Vortex <a href="#enabling-vortex" id="enabling-vortex"></a>

1. Go to **Administration** > **Configuration** > **AI capabilities** > **Vortex**.
2. Turn on the Vortex setting.

Once Vortex is enabled, the page links you to the install guide your developers follow, and to the Vortex dashboard.

If your instance does not have a Vortex subscription, the page shows what Vortex offers instead of the setting, with no way to turn it on. Add Vortex to your license first, see [Sonar product subscriptions](/sonarqube-server/instance-administration/license-management/product-subscriptions.md).

{% hint style="info" %}
Enabling Vortex does not configure anything on your developers' machines. Each developer installs Vortex in their own agent, and nothing reaches their agents until they do.
{% endhint %}

### Giving developers what they need <a href="#giving-developers-what-they-need" id="giving-developers-what-they-need"></a>

Each developer installs and connects Vortex in their own coding agent. Give them:

| What              | Value                                                                                                                                             |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Your instance URL | The base URL of your SonarQube Server, for example `https://sonarqube.example.com`                                                                |
| A user token      | Each developer generates their own under **My account** > **Security**. Project tokens, global tokens, and scoped organization tokens do not work |
| The project key   | The key of the project they work on, which Vortex uses to find the stored analyzer context                                                        |

{% hint style="warning" %}
Vortex needs access to the files on the developer's machine, so it does not work through the SonarQube Server-hosted MCP server, which is reached over HTTP. Developers use the SonarQube CLI, a SonarQube agent plugin, or a locally running SonarQube MCP Server instead.
{% endhint %}

For the install steps, see [Prerequisites](/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/how-to-guides/vortex-prerequisites.md) and the [Installing Vortex](/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/how-to-guides.md) for each coding agent.

## Checking adoption <a href="#checking-adoption" id="checking-adoption"></a>

The Vortex dashboard helps you track impact, adoption, and coverage, and Vortex's activity across your instance. It fills in as your developers install Vortex and work with it, so expect it to be empty right after you enable Vortex.

The dashboard reports only your developers' own use of Vortex through the SonarQube CLI, a SonarQube agent plugin, or a locally running SonarQube MCP Server. It does not include the Remediation Agent's own use of Vortex analysis to verify its fix suggestions.

To understand what counts as one tool call, see [#what-counts-as-a-tool-call](#what-counts-as-a-tool-call "mention").

## Related pages <a href="#related-pages" id="related-pages"></a>

* [What is Sonar Vortex?](/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex.md)
* [Installing Vortex](/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/how-to-guides.md)
* [Remediation Agent](/sonarqube-server/instance-administration/ai-features/remediation-agent.md)
* [Installation overview](/sonarqube-server/server-installation/ai-agents/installation-overview.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sonarsource.com/sonarqube-server/instance-administration/ai-features/sonar-vortex.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.