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.

See Before you start first. It covers the network access your storage backend needs from the runtime containers.

Choosing a backend

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

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.

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.

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

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

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.

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 Data lifecycle.

Sizing

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.

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.

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

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

With storage provisioned, size your deployment. See Capacity planning.

Related pages

• Before you start

• Configuration reference

• Troubleshooting

• Capacity planning