> 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/server-installation/ai-agents/shared-storage.md).

# Setting up shared storage

Provision shared storage for SonarQube Server agentic jobs, choose a backend, set a retention policy, and size the capacity you need. This page is for SonarQube Server 2026.5.

The Agent Orchestrator and the agent runtime containers exchange data through shared storage. The Orchestrator writes a snapshot of your source code there, the runtime reads it and writes its results back, and the Orchestrator picks the results up again.

Provision one backend before you deploy. Startup fails with an explicit error if the configured backend is unreachable.

{% hint style="info" %}
See [Before you start](/sonarqube-server/server-installation/ai-agents/before-you-start.md) first. It covers the network access your storage backend needs from the runtime containers.
{% endhint %}

## Choosing a backend <a href="#choosing-a-backend" id="choosing-a-backend"></a>

You can use either of two backends. Both carry the same data, so the choice is about what your infrastructure already provides.

| Backend                      | Use it when                                                                        |
| ---------------------------- | ---------------------------------------------------------------------------------- |
| S3-compatible object storage | You already run object storage, or you're on a cloud platform. This is the default |
| Shared filesystem            | You'd rather mount a volume than run an object store                               |

SonarQube Server doesn't manage the backend. You provide the endpoint, the location, and the credentials, and you own the backup and retention policy.

Any S3-compatible endpoint or shared filesystem works, wherever it runs: on-premises, in the cloud, or a mix of both.

### S3-compatible object storage <a href="#s3-compatible" id="s3-compatible"></a>

Any S3-compatible endpoint works. Tested and reported categories include:

* Cloud-managed: Amazon S3, and S3-compatible gateways in front of Google Cloud Storage or Azure Blob Storage
* On-premises: MinIO, Ceph Object Gateway, NetApp StorageGRID, and Dell ECS
* Self-hosted, for small or air-gapped deployments: MinIO running as a container alongside SonarQube Server

Create a bucket for job artifacts and give both the Orchestrator and the runtimes credentials for it.

{% hint style="info" %}
Most S3-compatible endpoints need path-style access enabled. Amazon S3 does not. Set path-style access accordingly, or requests fail with an addressing error.
{% endhint %}

When you use object storage, the runtime containers need outbound access to the storage endpoint. Include it when you restrict their egress, or every job fails while trying to download the staged code.

### Shared filesystem <a href="#shared-filesystem" id="shared-filesystem"></a>

Provide a filesystem path that both the Orchestrator and the runtime containers can read and write.

| Deployment     | How to provide it                                                                                                                                |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Kubernetes     | A `PersistentVolume` with the `ReadWriteMany` access mode. Any CSI-compatible backend works, including NFS, SMB, Azure Files, Ceph, and Longhorn |
| Docker Compose | A named volume or a bind mount, shared between the services                                                                                      |

The `ReadWriteMany` access mode is required on Kubernetes, because the Orchestrator and the job containers mount the same volume at the same time.

## Setting a retention policy <a href="#retention" id="retention"></a>

SonarQube Server deletes agentic job artifacts automatically. Set how long to keep them in **General Settings** > **Housekeeping** > **Agentic**:

| Setting (UI label)                           | Property                                 | Default |
| -------------------------------------------- | ---------------------------------------- | ------- |
| Delete Hunter job artifacts after            | `sonar.hunteragent.deleteOlderThan`      | 30 days |
| Delete Remediation Agent job artifacts after | `sonar.remediationagent.deleteOlderThan` | 30 days |

Set either value to `0` or less to disable automatic deletion for that agent.

As a backup, you can also set a lifecycle policy on the storage backend itself:

* On object storage, set a lifecycle policy on the bucket
* On a shared filesystem, schedule your own housekeeping on the volume

Monitor the size of the bucket or volume, and alert before it fills. Jobs fail when storage is exhausted.

{% hint style="warning" %}
Apply a storage-level policy to the job artifact location only. Vortex analysis keeps analyzer context in shared storage too: it manages its own lifecycle, and deleting current context costs you analysis precision. See [Installation overview](/sonarqube-server/server-installation/ai-agents/installation-overview.md#data-lifecycle).
{% endhint %}

## Sizing <a href="#sizing" id="sizing"></a>

Storage use is driven by how many jobs you run, not by how many projects you have. Two figures matter, and they behave differently.

Durable use is what accumulates. Each completed job leaves roughly 1 MB of results, logs, and issue detail:

```
Durable storage ≈ jobs per day × retention period in days × 1 MB
```

Peak use is what you need at any one moment. While a job runs, a compressed archive of the repository sits in storage as well:

```
Peak storage ≈ concurrent jobs × average compressed repository size
```

Add the two together to size the backend. For example, 500 jobs a day with a 14-day retention period needs about 7 GB of durable capacity, plus headroom for the archives of the jobs in flight.

{% hint style="info" %}
These figures come from measured jobs on a validation instance, so treat them as a starting point and revise them against your own usage once you have it. Repository size varies far more between projects than the per-job overhead does.
{% endhint %}

These figures cover agent job artifacts only. If you deploy Vortex analysis, it stores analyzer context in shared storage as well, and that context is considerably larger. Size it separately, see [Installation overview](/sonarqube-server/server-installation/ai-agents/installation-overview.md#storage-capacity).

The database also grows, but slowly and predictably. It holds job metadata only, with no large objects, plus a small permanent record for every issue that has been remediated. It's worth monitoring on very active instances, but it isn't the number that determines your storage.

## Housekeeping <a href="#housekeeping" id="housekeeping"></a>

Housekeeping is what actually deletes job artifacts from shared storage: the Agent Orchestrator runs a purge task on the interval set by `sonar.agentic.orchestrator.purge.interval` (default `24h`), removing artifacts older than the cutoff you configured above.

## Next step <a href="#next-step" id="next-step"></a>

With storage provisioned, size your deployment. See [Capacity planning](/sonarqube-server/server-installation/ai-agents/capacity-planning.md).

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

* [Before you start](/sonarqube-server/server-installation/ai-agents/before-you-start.md)
* [Configuration reference](/sonarqube-server/server-installation/ai-agents/configuration-reference.md)
* [Troubleshooting](/sonarqube-server/server-installation/ai-agents/troubleshooting.md)
* [Capacity planning](/sonarqube-server/server-installation/ai-agents/capacity-planning.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/server-installation/ai-agents/shared-storage.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.