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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Hand off a long task.
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.