# How to Configure S3 Asset Storage for OpenMAIC Deployments

> Configure S3 asset storage for OpenMAIC deployments by setting the ASSET_S3_BUCKET environment variable. Persist assets to Amazon S3 without code changes.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: how-to-guide
- Published: 2026-08-31

---

**You can configure S3 asset storage for OpenMAIC deployments by setting the `ASSET_S3_BUCKET` environment variable, which instructs the framework to lazily instantiate an `S3AssetByteStore` that persists assets to Amazon S3 without requiring any code changes.**

The THU-MAIC/OpenMAIC repository implements a persistence abstraction layer that supports both local disk and cloud object storage backends. By leveraging environment variables, you can configure S3 asset storage for OpenMAIC deployments across Vercel, Docker, Kubernetes, or bare-metal servers while maintaining a declarative configuration approach.

## Required Environment Variables

OpenMAIC detects S3 configuration through specific environment variables defined in [`lib/persistence/asset-byte-store.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/persistence/asset-byte-store.ts). When `ASSET_S3_BUCKET` is present, the factory function `lazyAssetByteStore()` creates an S3-backed store instead of the default local implementation.

Set these variables to enable AWS S3 storage:

- **`ASSET_S3_BUCKET`** – The name of your existing S3 bucket (e.g., `my-openmaic-assets`). This triggers the S3 storage path.
- **`AWS_ACCESS_KEY_ID`** – Your AWS access key.
- **`AWS_SECRET_ACCESS_KEY`** – Your AWS secret key.
- **`AWS_REGION`** – The AWS region where your bucket resides (e.g., `us-east-1`).

The S3 client uses the standard AWS SDK lookup chain, so credentials can also be provided via IAM instance profiles or `~/.aws/credentials` files rather than explicit environment variables.

## Configuring S3-Compatible Services

For MinIO, LocalStack, or other S3-compatible services, you must specify additional endpoint parameters. These are passed directly to the underlying `S3Client` constructor in `packages/@openmaic/storage/src/asset/s3-bytes.ts`.

Add these optional variables:

- **`S3_ENDPOINT`** – Custom endpoint URL (e.g., `http://minio.local:9000`).
- **`S3_FORCE_PATH_STYLE`** – Set to `true` for services that do not support virtual-hosted style buckets.

## Deployment Configuration Examples

### Local Development with dotenv

Create a `.env` file in your project root for local development:

```dotenv
ASSET_S3_BUCKET=my-openmaic-assets
AWS_ACCESS_KEY_ID=YOUR_ACCESS_KEY
AWS_SECRET_ACCESS_KEY=YOUR_SECRET_KEY
AWS_REGION=us-east-1

```

### MinIO or LocalStack Configuration

For testing with a local MinIO instance:

```dotenv
ASSET_S3_BUCKET=openmaic-test
S3_ENDPOINT=http://minio.local:9000
S3_FORCE_PATH_STYLE=true
AWS_ACCESS_KEY_ID=minio_key
AWS_SECRET_ACCESS_KEY=minio_secret
AWS_REGION=us-east-1

```

### Docker Compose Setup

Deploy to production with Docker Compose by injecting environment variables:

```yaml
services:
  openmaic:
    image: ghcr.io/thu-maic/openmaic:latest
    environment:
      - ASSET_S3_BUCKET=maic-prod
      - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}
      - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}
      - AWS_REGION=eu-west-1

```

### Programmatic Verification

You can verify the active store implementation at runtime:

```typescript
import { lazyAssetByteStore } from '@/lib/persistence/server-provider';

// The store initializes as S3AssetByteStore when ASSET_S3_BUCKET is set
const assetStore = await lazyAssetByteStore(process.env.ASSET_S3_BUCKET, true);
console.log('Asset store type:', assetStore.constructor.name);

```

## Implementation Details

The S3 integration relies on two key components in the OpenMAIC codebase.

**[`lib/persistence/asset-byte-store.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/persistence/asset-byte-store.ts)** validates the `ASSET_S3_BUCKET` variable and manages the lifecycle of the byte store. It implements **lazy loading** — the AWS SDK is only imported the first time an asset operation is invoked. This means deployments that never touch assets run without the optional AWS SDK dependency, reducing cold start times and bundle size.

**`packages/@openmaic/storage/src/asset/s3-bytes.ts`** contains the `S3AssetByteStore` class, which implements the asset storage interface using S3. It handles binary `put`, `get`, and `delete` operations, along with presigned URL generation for temporary access. The class accepts the optional `S3_ENDPOINT` and `S3_FORCE_PATH_STYLE` parameters to support non-AWS object storage services.

## Summary

- **Set `ASSET_S3_BUCKET`** to enable S3 storage; otherwise, OpenMAIC defaults to local disk.
- **Use standard AWS credentials** (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`) or rely on IAM instance profiles.
- **Configure `S3_ENDPOINT` and `S3_FORCE_PATH_STYLE`** when using MinIO, LocalStack, or other S3-compatible APIs.
- **Lazy loading** ensures the AWS SDK is only imported when asset operations occur, keeping lightweight deployments fast.
- No code changes are required to switch storage backends—only environment variable updates.

## Frequently Asked Questions

### How does OpenMAIC handle AWS credentials when running on EC2 or EKS?

When deployed to AWS infrastructure, OpenMAIC follows the standard AWS SDK credential chain. If you omit `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`, the `S3AssetByteStore` automatically retrieves temporary credentials from the EC2 instance profile or EKS IAM Roles for Service Accounts (IRSA), eliminating the need to manage static keys in production.

### Can I use OpenMAIC without installing the AWS SDK?

Yes. The AWS SDK is an optional dependency. According to the source code in [`lib/persistence/asset-byte-store.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/persistence/asset-byte-store.ts), the SDK is loaded lazily—only when `ASSET_S3_BUCKET` is set and an asset operation is actually invoked. Deployments using only local storage never import the AWS libraries, keeping bundle sizes smaller.

### What S3 operations does OpenMAIC support?

The `S3AssetByteStore` class in `packages/@openmaic/storage/src/asset/s3-bytes.ts` implements the full asset persistence interface, including `put` for uploads, `get` for downloads, `delete` for removal, and presigned URL generation for temporary public access. These operations cover all standard asset management needs for images, videos, and PDFs.

### How do I migrate existing local assets to S3?

OpenMAIC does not include a built-in migration utility. To migrate, write a script that reads assets from your local disk using the file-system provider, then writes them to S3 using the `S3AssetByteStore` methods. Once migrated, set `ASSET_S3_BUCKET` and restart your deployment to point new requests to the S3 backend.