# Add S3 File Storage to a Medusa Backend

Yes. An agent registers Medusa's S3 file provider in medusa-config.ts behind environment variables, keeps local storage for development, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-s3-file-storage/medusa/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how the backend is configured. In a monorepo laid out like medusajs/dtc-starter, `apps/backend` is a Medusa 2.22 application on Node 22 managed with pnpm 10 and Turborepo, and `apps/backend/medusa-config.ts` holds only a `projectConfig`: `databaseUrl` from `DATABASE_URL`, the three CORS lists, and the JWT and cookie secrets, all loaded through `loadEnv`. There is no `modules` array at all, so every module runs with Medusa's defaults, and for files that default is the local provider, which writes uploads to a directory on the server's disk and serves them from the backend's own URL. `.env.template` lists `STORE_CORS`, `ADMIN_CORS`, `AUTH_CORS`, `REDIS_URL`, `JWT_SECRET`, `COOKIE_SECRET`, `DATABASE_URL` and `DB_NAME`, and nothing about storage; `.gitignore` already ignores an `/uploads` directory from an earlier layout.

The starter's own `AGENTS.md` sends module and plugin configuration to `medusa-config.ts` and nowhere else, which is where the agent makes the change: a `modules` array with one entry that resolves `@medusajs/medusa/file` and lists a single provider. The provider is `@medusajs/medusa/file-s3` under the id `s3` when `S3_BUCKET` is set, with `file_url`, `access_key_id`, `secret_access_key`, `region`, `bucket` and `endpoint` read from `S3_FILE_URL`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_REGION`, `S3_BUCKET` and `S3_ENDPOINT`, and the local provider otherwise, so a developer with no bucket keeps working from `.env.template` unchanged. Both providers ship inside `@medusajs/medusa`, so `package.json` gains no dependency.

`endpoint` is kept optional on purpose: an S3-compatible store such as Cloudflare R2 or MinIO needs it, and MinIO also needs path-style addressing, which the provider takes through `additional_client_config` with `forcePathStyle` set; the agent writes that option in a comment beside the entry rather than enabling it, because a real S3 bucket must not have it. `file_url` is the public base the backend prepends to each key when it hands a URL to the admin dashboard or the storefront, so the agent notes in `.env.template` that it is the bucket's public address or the CDN in front of it, and that the bucket's object access policy decides whether those URLs resolve.

The agent then proves the configuration loads. It runs `pnpm install` at the root, `pnpm --filter @dtc/backend build`, which compiles `medusa-config.ts` and the `src/` tree, and `pnpm --filter @dtc/backend exec tsc --noEmit`, so a wrong option name or a missing import fails here rather than at the first `medusa start`. With `S3_BUCKET` unset the existing `test:unit` command runs against the local provider as before. The pull request shows the config diff, the new `.env.template` lines, and the build and type-check output, and says where product images are read from in the storefront, `apps/storefront/src/lib/data/`, so the reviewer knows which pages change once a bucket is in use.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add S3 file storage to this Medusa backend. Read AGENTS.md, apps/backend/medusa-config.ts, apps/backend/.env.template, apps/backend/package.json and the root package.json and pnpm-workspace.yaml first. In medusa-config.ts add a modules entry that resolves @medusajs/medusa/file with one provider: @medusajs/medusa/file-s3 under the id s3 when S3_BUCKET is set, with file_url, access_key_id, secret_access_key, region, bucket and endpoint read from S3_FILE_URL, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, S3_REGION, S3_BUCKET and S3_ENDPOINT, and the local provider otherwise. Add the six variables to .env.template with a one-line note each, and a comment showing the additional_client_config forcePathStyle option for MinIO without enabling it. Add no dependency. Run pnpm install, pnpm --filter @dtc/backend build and a tsc --noEmit on the backend, then the backend's test:unit command, and open a pull request that shows the config diff and the build output and names where the storefront reads image URLs.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request changes `apps/backend/medusa-config.ts` and `apps/backend/.env.template` and nothing else: no new package, no migration, no change to the storefront. Its description carries the config diff, the six new variables with their one-line notes, the `medusa build` and `tsc --noEmit` output, and the `test:unit` result with the local provider still selected.

After a deploy with the six variables set, every upload from the admin dashboard, product images and import files included, goes to the bucket under the key the provider generates, and the URL the backend stores for each file starts with `S3_FILE_URL`, which the storefront's data layer passes through to the image components. Files uploaded before the change stay on the old server disk and keep their old URLs until someone moves them, which the description calls out as a separate task.

Before merging, a reviewer confirms the bucket's object access policy matches how `file_url` will be used, decides whether a CDN should sit in front of the bucket so `S3_FILE_URL` points at it, and checks that the deployment's secret store holds the access key pair rather than `.env`.

## Run it on every new store

An agency that stands up a Medusa backend per client sends this body once per repository from its own server, each a `POST /o/{org}/sessions` with that repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own `medusa-config.ts`: a backend that already lists other modules gets the file module appended, and one that already names a file provider is reported and left alone.

Once the module is configured, an automation on the Project with a `github` trigger on `pull_request.opened` and the prompt "if this pull request changes medusa-config.ts, say in a comment which modules and providers it adds or removes and whether .env.template names every variable they read; push nothing" starts one run per pull request. The trigger adds the pull request after the prompt, only work by an owner, member or collaborator fires it, and its runs read the repository and comment.

## Why run it on Rush?

Storage is one of the first things a Medusa project moves off the server disk, and the change is small but easy to get subtly wrong: an option name that the provider ignores, a `file_url` that does not match the bucket's access policy, or a path-style flag that breaks real S3. The agent writes the entry against the installed Medusa version, keeps the local provider as the fallback, and runs the build and type check so the configuration is known to load before it is reviewed.

The build log, the type check and the unit test output stay with the run, and the pull request explains each variable in a line so the person deploying it does not need the Medusa docs open. An agency with many backends runs the same request across all of them at once, each in its own sandbox, and gets one pull request per repository fitted to that backend's existing modules.

## Frequently asked questions

### Do I need to install a package?

No. Both the local and the S3 file providers ship inside `@medusajs/medusa` and are resolved by the `@medusajs/medusa/file-local` and `@medusajs/medusa/file-s3` paths, so `package.json` and the lockfile do not change.

### What happens in development without a bucket?

With `S3_BUCKET` unset, the entry selects the local provider, which is what the backend used before the change, so `pnpm dev` and the unit tests behave as they did. Setting the six variables in `.env` switches that machine to the bucket.

### Does it work with Cloudflare R2 or MinIO?

Yes. Both take the `endpoint` option, which the agent reads from `S3_ENDPOINT`; MinIO also needs path-style addressing through `additional_client_config`, which the pull request shows in a comment and leaves off because real S3 must not use it.

### What about files that were already uploaded?

They stay where they are, on the server disk with their old URLs, since the provider only handles uploads made after the change. Moving them to the bucket and rewriting their stored URLs is a data migration the description names as a separate task.

## More Medusa jobs

- [Add a Scheduled Job to a Medusa Backend](https://getrush.ai/run/add-scheduled-job/medusa/)
- [Add Stripe Checkout to a Medusa Store](https://getrush.ai/run/add-stripe-checkout/medusa/)
- [Write Integration Tests for a Medusa Backend](https://getrush.ai/run/write-integration-tests/medusa/)

## More jobs like this: Hand off a long task

- [Add AddressSanitizer and UBSan CI to a CMake Project](https://getrush.ai/run/add-sanitizer-ci/cmake/)
- [Add an SBOM to a Gradle Build's CI](https://getrush.ai/run/add-sbom-to-ci/gradle/)
- [Add an SBOM to CI for a Maven Project](https://getrush.ai/run/add-sbom-to-ci/maven/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
