> 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/project-administration/ai-features/hunter-agent.md).

# Hunter Agent

Run Hunter Agent analyses and set up scheduled scans for a single project in SonarQube Server 2026.5.

SonarQube Hunter Agent runs a deep AI-powered analysis of your projects to find vulnerabilities that require human-like understanding of the code, such as broken access control and business-logic flaws, then raises them as issues you triage like any other.

Before choosing projects to analyze, see [Which projects benefit most?](/agent-centric-development-cycle/in-your-long-living-branches-the-code-maintenance-loop/hunter-agent.md#which-projects-benefit-most) in the Agent Centric Development Cycle documentation.

An Instance Admin enables the agent for the instance and configures its LLM provider. See [Hunter Agent](/sonarqube-server/instance-administration/ai-features/hunter-agent.md) for the full details.

As a project administrator, you run analyses manually or set up a scan schedule for your project.

## Running analyses with Hunter Agent <a href="#running-analyses" id="running-analyses"></a>

> If you're running the first Hunter Agent analysis for your project, see [First analysis recommendations](#first-analysis-recommendations) to avoid failing your quality gate on the main branch.

Make sure you have the **Administer** permission on the project. You can then run Hunter Agent analyses manually or set up scheduled analyses.

1. Open the project you want to scan.
2. Go to **Analysis** > **Hunter Agent** on your project.
3. If you see a message that the agent isn't enabled, ask an administrator to enable it first, using the link in the message.
4. If the project isn't bound to its DevOps platform, bind it first, following the prompt.
5. Run a Hunter Agent analysis manually or schedule analyses:
   * Manually: Choose the branch to scan from the heading branch selector then click **Scan Now**.
   * On a schedule: Click **Manage scheduling** in the page header. Turn on scheduled scans, then choose the branch to scan, the frequency, and the time and timezone.

## First analysis recommendations <a href="#first-analysis-recommendations" id="first-analysis-recommendations"></a>

The Hunter Agent raises its findings as regular issues. Running your first analysis directly on the main branch can cause a passing quality gate to fail and block your team before you've had a chance to work through the findings.

To roll out the agent without disrupting your main branch:

1. Start on a dedicated branch. For your first analysis, run the agent on a dedicated branch instead of your main branch. The findings surface as issues on that branch, so they do not affect your main branch's quality gate.
2. Work through the backlog. Triage, assign, and resolve the findings the agent raises, the same way you handle any other issue.
3. Schedule analyses on the main branch. After your fixes are merged into the main branch and the number of open findings is under control, set up scheduled analyses so the agent keeps covering it.

This approach keeps the first wave of findings off your main branch. It gives your team time to clear the backlog and brings the agent into your main-branch quality gate only once the results are manageable.

Alternatively, you can run the first analysis directly on your main branch and **Accept** the findings you do not fix immediately. Accepted findings no longer affect the quality gate, so they do not block your team while you work through the backlog.

## Viewing findings <a href="#viewing-findings" id="viewing-findings"></a>

The agent raises its findings as issues in your project. See [Hunter Agent findings](/sonarqube-server/user-guide/issues/with-ai-features/hunter-agent-findings.md) to review and triage them.

## When the agent is not available for your project <a href="#agent-not-available" id="agent-not-available"></a>

| Message                                           | What it means                                                 | What to do                                                                                           |
| ------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| The Hunter Agent is not enabled for this instance | An instance administrator has not turned on the Hunter Agent. | Contact your instance administrator.                                                                 |
| This project is not bound to a repository         | The agent has no repository to scan.                          | Project administrators can select **Set up project binding**. Otherwise, contact your administrator. |

If you start an analysis while one is already running on the same branch, a dialog tells you a scan is already in progress and does not start a second one.

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

* Instance admin: [Hunter Agent](/sonarqube-server/instance-administration/ai-features/hunter-agent.md)
* [Hunter Agent findings](/sonarqube-server/user-guide/issues/with-ai-features/hunter-agent-findings.md)
* AC/DC: [Hunter Agent](/agent-centric-development-cycle/in-your-long-living-branches-the-code-maintenance-loop/hunter-agent.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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.sonarsource.com/sonarqube-server/project-administration/ai-features/hunter-agent.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.