> For the complete documentation index, see [llms.txt](https://docs.unitlab.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.unitlab.ai/documentation/data/cloud-providers.md).

# Cloud providers

Connect approved cloud storage and import the exact source prefix.

Connect your storage, browse a selected folder, and register its media in Unitlab. This guide uses an S3 example with two images and a nested folder, so you can verify the selected scope before importing a larger collection.

## Before you start

You need **Manage cloud storage** permission to create or change the connection. Prepare the bucket or container name, region where required, credentials, and the prefix you want to browse. Use a dedicated organization-owned identity with access to the source files and generated-data locations described below.

Start with a small collection so you can check the images and previews before importing more data.

![Workspace Add Cloud Storage dialog](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2FEceeKlJexxGEUrAINYfa%2Fcloud-storage-add.png?alt=media\&token=7f2c7aff-bb2a-476f-87cb-a8bd3a70540f)

*The connection is created in Workspace Settings › Cloud storage. After it shows Connected, return to Data Space › Assets and use New Folder › Add Cloud Folder to choose the connection and exact source scope.*

## Supported providers

The current Add Cloud Storage dialog offers:

* Amazon S3;
* Google Cloud Storage;
* Azure Blob Storage;
* MinIO;
* DigitalOcean Spaces;
* Cloudflare R2;
* Wasabi;
* Backblaze B2;
* custom S3-compatible storage.

The exact credential fields vary by provider, but the current configuration model includes a display name, bucket or container, credentials, region where applicable, and an optional prefix or sub-path. The prefix sets the location Unitlab browses and uses within the bucket. Enforce the intended object-access boundary in the storage provider's permissions too.

The SDK can list safe storage metadata, browse a prefix, create a cloud-backed Unitlab folder, synchronize it, and import selected files or directory paths into a project. Cloud credentials are not returned by SDK list or browse operations.

## Example bucket and connection

Assume the bucket has this layout:

```
example-bucket/
└── datasets/
    └── incoming/
        ├── road.jpg
        ├── crossing.jpg
        └── later/
            └── tunnel.jpg
```

Use your own bucket name and files. For this example, configure:

| Field                        | Example value            | Meaning                                         |
| ---------------------------- | ------------------------ | ----------------------------------------------- |
| Display name                 | `Road scenes S3`         | A recognizable name inside Unitlab.             |
| Bucket                       | `example-bucket`         | The existing bucket, without `s3://` or a path. |
| Region                       | Your bucket's AWS region | Must match the bucket.                          |
| Prefix                       | `datasets/`              | The root exposed by this connection.            |
| Source folder selected later | `incoming/`              | Relative to the connection prefix.              |

Selecting `incoming/` should register `road.jpg` and `crossing.jpg` at that level. The nested `later/` folder is handled separately. Do not enter `datasets/incoming/` again when the connection already has prefix `datasets/`.

## Connect Amazon S3

In **Workspace Settings > Cloud storage**, choose **Amazon S3** and provide the bucket name, region, access key ID, secret access key, and optional prefix. Use a dedicated identity with access to the required source objects and the generated-data location described below.

The built-in S3 connection uses an access key and secret key. It does not expose role ARN, AssumeRole, external ID, or session-token configuration. Temporary STS credentials require a session token and cannot be entered as a key-secret pair alone. The Python SDK uses a connection already created in Workspace Settings; it does not create or rotate the provider credentials.

## What stays in S3 and what Unitlab processes

Cloud import registers the original image's bucket and object reference. It does not first upload another original copy into Unitlab's bucket. Unitlab still reads the image bytes for viewing and processing, and stores metadata and annotations in Unitlab.

Ordinary project-image thumbnails and annotation previews are written back to the connected bucket under a generated namespace:

```
<connection-prefix>/unitlab-<workspace-id-prefix>/thumbnails/...
<connection-prefix>/unitlab-<workspace-id-prefix>/thumbnail_annotations/...
```

The workspace ID prefix is the first eight characters of its UUID. With no connection prefix, these paths start at the bucket root. They are separate from the original image keys and are not necessarily inside the subfolder chosen for one import.

This is not a read-only storage integration or a guarantee that no derived image is stored elsewhere. Other features have their own processing needs. For example, Find Similar workflow reference crops are stored in Unitlab's platform storage for model use. Review the features you intend to use when defining storage and processing requirements.

## S3 access and connection checks

For ordinary image import, prepare these permissions with your storage administrator:

| Purpose                                                         | Access needed                                                                        |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Validate the bucket and browse objects                          | `s3:ListBucket` on the bucket.                                                       |
| Check the AWS CORS configuration                                | `s3:GetBucketCORS` on the bucket.                                                    |
| Read source images and their metadata                           | `s3:GetObject` on the selected source objects.                                       |
| Create and read generated previews                              | `s3:PutObject` and `s3:GetObject` on the Unitlab-generated namespace.                |
| Clean up generated data where required by the selected workflow | `s3:DeleteObject` on the generated namespace, rather than on original source images. |

The connection check reads bucket availability and CORS settings. It does not upload or delete a test object, so **Connected** does not prove that every source can be read or that preview writes will succeed. Import a small sample and check that processing and preview generation finish.

Allow browser GET requests from your Unitlab application's exact origin in the bucket CORS configuration. For the hosted application, that origin is `https://platform.unitlab.ai`. Unitlab reads this configuration; the bucket administrator sets it. AWS documents the required actions for [bucket access](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadBucket.html), [CORS reads](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketCors.html), and [object operations](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-with-s3-policy-actions.html).

A prefix-conditioned `ListBucket` policy can reject the initial bucket check because that check has no prefix parameter. Encrypted objects can also require access to the relevant KMS key. Validate the actual policy against your deployment instead of treating the table as a universal IAM policy.

If writes fail with `AccessControlListNotSupported`, confirm that the deployment supports buckets with ACLs disabled. Older deployments send a private ACL on generated-object uploads. Adding more IAM permissions does not make that request compatible with Bucket owner enforced storage.

## Register and verify a cloud folder

{% stepper %}
{% step %}

### Save and test the connection

In **Workspace Settings > Cloud storage**, save the provider details. For the example, choose Amazon S3 and use the bucket and prefix from the table above. Confirm that the connection shows **Connected**.

This checks the connection, not every object's read or write permissions. The following sample import verifies those too.
{% endstep %}

{% step %}

### Add the source folder to Assets

Open **Data Space > Assets**, then **New Folder ▾ > Add Cloud Folder**. Choose `Road scenes S3`, select the relative sub-prefix `incoming/`, and give the folder a descriptive display name such as `Incoming road scenes`.

Unitlab creates a root folder representing that location. The card shows the provider badge and source path.
{% endstep %}

{% step %}

### Open the folder and check its contents

Opening a cloud folder that has never been synchronized registers its first level automatically. For this example, expect two image assets, `road.jpg` and `crossing.jpg`, and a child cloud folder named `later`.

Wait for image processing and check that previews load. Open `later` separately to register and inspect `tunnel.jpg`.
{% endstep %}

{% step %}

### Refresh when the source changes

Use **Sync** to refresh the current cloud-folder level. Check the resulting files and processing states. Sync does not recursively register every child folder or synchronize project annotation work back to a dataset.
{% endstep %}

{% step %}

### Bring the data into a project

To use a curated dataset snapshot, publish the validated Assets selection as a dataset version, then attach that version to the project. Alternatively, use the project's **Upload > Storage** flow to select files directly from the connection.

For a project import of the two immediate images, check that the Batch Queue contains the selected files and has no processing failures before adding labels. See [Data upload](/documentation/data/data-upload.md), [Python cloud imports](https://docs.unitlab.ai/api-sdk-cli/sdks/cloud-storage), or the [HTTP Cloud storage API](https://docs.unitlab.ai/api-sdk-cli/apis/cloud-storage-api).
{% endstep %}
{% endstepper %}

Cloud folders are read-only mirrors for organization, so drag-move is disabled. This interface restriction does not mean that processing never writes generated objects to the bucket. The original-reference and generated-data behavior is described above.

Connection administrators can create, update, delete, test, and browse integrations from Workspace Settings. Keep the connection owner and credential-rotation process recorded with your workspace configuration.

## Import existing labels for S3 images

On deployments that support annotation import, S3-referenced images can receive existing model predictions without uploading another copy of the originals. Import or attach the images into a project first and wait for processing. Then use [Import local annotations](https://docs.unitlab.ai/documentation/data/import-local-annotations) or [Python SDK annotation imports](https://docs.unitlab.ai/api-sdk-cli/sdks/annotation-imports) to preview and save supported label JSON.

Match the cloud key shown for the project item, or map the exact project-media ID. Keep subfolder names when they distinguish otherwise identical filenames. Annotation JSON may be local or read from a connected storage key; a URL written inside JSON does not register or download its media. The imported labels remain editable and follow the project's review process. Annotation-import availability depends on the deployed backend as well as the SDK version.

## Check the result before expanding the import

For the sample collection, confirm that the selected images open, thumbnails load, and the project import has no failed items. If connection validation succeeds but previews fail, check source-read and generated-preview write permissions separately. If a request times out, inspect the existing folder or Batch Queue before repeating it.

After the sample succeeds, use the same connection with another explicit prefix or object selection. Review access when the source or connection owner changes.

***

> **Continue with Unitlab:** [Unitlab’s data curation platform](https://unitlab.ai/en/data-curation)

## Model predictions to a reviewed delivery

Follow [Pre-labels, review, and export](https://docs.unitlab.ai/api-sdk-cli/sdks/prelabels-review-and-export) for the complete workflow and the limits of approved-only filtering.