> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognee.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Object Storage

> Configure S3 and S3-compatible storage (Cloudflare R2, MinIO) as Cognee's data/system storage

Use object storage for the data and system directories when running Cognee in distributed environments (containers, Kubernetes, multi‑node). Amazon S3 and any S3-compatible service (Cloudflare R2, MinIO, etc.) are supported today via the `AWS_ENDPOINT_URL` environment variable.

## When to use

* Containers/servers without a shared local disk
* Centralized storage for `data_root_directory` and `system_root_directory`
* Easy backups and lifecycle policies

## Configuration

<Tabs>
  <Tab title="Amazon S3">
    Use this for native AWS S3 buckets.

    ```bash theme={null}
    STORAGE_BACKEND=s3
    STORAGE_BUCKET_NAME=my-cognee-bucket
    AWS_ACCESS_KEY_ID=<aws-access-key-id>
    AWS_SECRET_ACCESS_KEY=<aws-secret-access-key>
    AWS_REGION=us-east-1
    DATA_ROOT_DIRECTORY=s3://my-cognee-bucket/cognee/data
    SYSTEM_ROOT_DIRECTORY=s3://my-cognee-bucket/cognee/system
    ```

    `AWS_ENDPOINT_URL` is not required for standard Amazon S3.

    For AWS-hosted deployments, `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` are optional when the runtime already has ambient AWS credentials. If both values are omitted, Cognee defers to boto3/s3fs's default credential resolution chain, including EC2 instance profiles, ECS task roles, EKS IRSA (IAM Roles for Service Accounts), shared credentials files, and `AWS_PROFILE`.

    If you set either `AWS_ACCESS_KEY_ID` or `AWS_SECRET_ACCESS_KEY` explicitly, set both. `AWS_SESSION_TOKEN` is also supported when using temporary credentials.
  </Tab>

  <Tab title="Cloudflare R2">
    Use this for Cloudflare R2 buckets through the S3-compatible API.

    ```bash theme={null}
    STORAGE_BACKEND=s3
    STORAGE_BUCKET_NAME=my-cognee-bucket
    AWS_ACCESS_KEY_ID=<r2-access-key-id>
    AWS_SECRET_ACCESS_KEY=<r2-secret-access-key>
    AWS_ENDPOINT_URL=https://<account-id>.r2.cloudflarestorage.com
    AWS_REGION=auto
    DATA_ROOT_DIRECTORY=s3://my-cognee-bucket/cognee/data
    SYSTEM_ROOT_DIRECTORY=s3://my-cognee-bucket/cognee/system
    ```

    Get your R2 credentials from the Cloudflare dashboard under **R2 → Manage API tokens**. R2 is region-less, so `AWS_REGION=auto` is a convenient placeholder. Keep explicit R2 credentials configured for this S3-compatible endpoint.
  </Tab>

  <Tab title="MinIO">
    Use this for self-hosted or local MinIO deployments.

    ```bash theme={null}
    STORAGE_BACKEND=s3
    STORAGE_BUCKET_NAME=my-cognee-bucket
    AWS_ACCESS_KEY_ID=minioadmin
    AWS_SECRET_ACCESS_KEY=minioadmin
    AWS_ENDPOINT_URL=http://localhost:9000
    AWS_REGION=us-east-1
    DATA_ROOT_DIRECTORY=s3://my-cognee-bucket/cognee/data
    SYSTEM_ROOT_DIRECTORY=s3://my-cognee-bucket/cognee/system
    ```

    Create the bucket in MinIO before starting Cognee, for example with `mc mb myminio/my-cognee-bucket`. Keep explicit MinIO credentials configured for this S3-compatible endpoint.
  </Tab>
</Tabs>

The same `STORAGE_BACKEND=s3` backend is used for all three options. For S3-compatible providers, Cognee relies on `AWS_ENDPOINT_URL` to route requests to the correct API endpoint.

## Programmatic directories

```python theme={null}
import os
import cognee

bucket = os.getenv("STORAGE_BUCKET_NAME", "my-cognee-bucket")
data_dir = os.path.join("s3://", bucket, "data")
system_dir = os.path.join("s3://", bucket, "system")

cognee.config.data_root_directory(data_dir)
cognee.config.system_root_directory(system_dir)
```

## Verify

```python theme={null}
import cognee

await cognee.add("hello from s3")
await cognee.cognify()
res = await cognee.search("hello")
print(f"S3 OK, results: {len(res)}")
```

### How it works

`AWS_ENDPOINT_URL` is passed directly to `s3fs` as `endpoint_url`, which boto3/s3fs then uses instead of the default AWS endpoint. Any service that implements the S3 API will work.

## Next steps

* Short workflow: [S3 Storage guide](/guides/s3-storage)
* Deployment variants: `how-to-guides/cognee-sdk/deployment/index`