# Add a Dev Container to a Medusa Monorepo

Yes. An agent writes a .devcontainer for your Medusa monorepo with Node 22, pnpm and a Postgres service, boots it, runs the migrations, and opens a PR.

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

## What the agent does

The agent reads what a working machine needs before it writes one. In a repository laid out like medusajs/dtc-starter, the root `package.json` sets `engines.node` to `>=22.23.4` and `packageManager` to `pnpm@10.11.1`, `pnpm-workspace.yaml` declares `apps/**` and lists `@medusajs/telemetry` under `onlyBuiltDependencies`, and `turbo.json` wires `dev`, `build`, `lint`, `test` and `seed`. `apps/backend/package.json` runs `medusa develop`, which the `AGENTS.md` says listens on 9000 with the admin at `/app`, and `apps/storefront/package.json` runs `next dev -p 8000`. The README's prerequisites are Node v22.22+, PostgreSQL v15+ and pnpm v10+, and its setup copies `apps/backend/.env.template` to `.env`, fills `DATABASE_URL`, runs `pnpm medusa db:migrate` and creates an admin with `pnpm medusa user`. There is no Dockerfile, no compose file and no `.devcontainer/` anywhere, and `.gitignore` ignores `.vscode`, so editor settings have to travel inside the container definition.

It then reads what the backend actually connects to. `apps/backend/medusa-config.ts` passes only `databaseUrl` and the three CORS lists plus the JWT and cookie secrets to `defineConfig`; nothing names a Redis module, so the `REDIS_URL` line in `.env.template` is unused by this configuration and the container needs Postgres alone. `ADMIN_CORS` and `AUTH_CORS` list `localhost:5173` and `localhost:9000`, which tells the agent which ports to forward beyond 9000 and 8000. `apps/backend/jest.config.js` loads a `.env.test` through `loadEnv("test")` and the three suites in `package.json` run Jest with `--runInBand`, so the integration tests want their own database on the same server.

It writes `.devcontainer/devcontainer.json` and `.devcontainer/compose.yaml`. The compose file has an `app` service on a Node 22 dev container image with the repository bind-mounted, and a `db` service on `postgres:16` with a health check on `pg_isready` that `app` waits for. `devcontainer.json` names the `app` service, forwards 9000, 8000 and 5173 with labels, puts `DATABASE_URL` for the `db` host into `containerEnv`, and runs a `postCreateCommand` that enables corepack for `pnpm@10.11.1`, installs with `pnpm install --frozen-lockfile`, copies `.env.template` to `.env` when none exists, and runs `pnpm medusa db:migrate` in `apps/backend`, which also applies the `migration-scripts` seed. `customizations.vscode` carries the ESLint and Prettier extensions the root config expects. The storefront is left optional, as `AGENTS.md` insists, so the command touches `apps/storefront` only when the directory exists.

In its sandbox the agent installs Docker and the `@devcontainers/cli`, runs `devcontainer up --workspace-folder .` from a clean clone, and watches the `postCreateCommand` log for the install, the environment file and the migration output. It then runs `devcontainer exec` with `pnpm backend:dev`, waits for the server, and fetches `http://localhost:9000/health` from the host side of the forwarded port, then `/app` to confirm the admin bundle serves. It runs `pnpm lint` inside the container and `pnpm run test:unit` in `apps/backend` to show the toolchain works, and records the whole transcript.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add a Dev Container to this Medusa monorepo. Read package.json, pnpm-workspace.yaml, turbo.json, README.md, AGENTS.md, .gitignore, apps/backend/package.json, apps/backend/medusa-config.ts, apps/backend/.env.template, apps/backend/jest.config.js and apps/storefront/package.json first. Write .devcontainer/devcontainer.json and .devcontainer/compose.yaml with an app service on a Node 22 image and a Postgres service with a health check, forward the backend, storefront and admin ports the CORS lists name, set DATABASE_URL for the compose database, and add a postCreateCommand that activates the pnpm version from packageManager with corepack, installs with a frozen lockfile, creates apps/backend/.env from its template when missing and runs the Medusa migrations. Treat apps/storefront as optional. Only add a Redis service if medusa-config.ts configures a Redis module. Install Docker and the Dev Container CLI in your sandbox, bring the container up from a clean clone, start the backend inside it, request /health and /app through the forwarded port, run lint and the backend unit tests inside the container, and open a pull request that pastes the postCreateCommand log and the two responses. Do not add a Dockerfile for production and do not change any application code.",
  "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 adds `.devcontainer/devcontainer.json` and `.devcontainer/compose.yaml` and nothing else. Its description pastes the `devcontainer up` output with the corepack activation, the `pnpm install --frozen-lockfile` summary, the `.env` copy and the `db:migrate` log including the migration-scripts seed, followed by the `/health` and `/app` responses fetched through port 9000 and the lint and unit test output from inside the container.

A short table in the description maps each forwarded port to the `.env.template` line it came from, and a note explains why there is no Redis service: `medusa-config.ts` names no Redis module, so the event bus and cache stay in memory, and the `REDIS_URL` line in the template is left as it was.

Before merging, a reviewer decides whether the Postgres major should match production rather than the README's minimum, whether the migration belongs in `postCreateCommand` or in a documented manual step, and whether the storefront's `NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY`, which only exists after the admin is created, should be filled by a script or left to the developer.

## Run it on every repository with a README setup section and no .devcontainer

Start one run per repository from your own server: `POST /o/{org}/sessions` with this prompt and that repository in `resources`, one call each. `GET /o/{org}/github` lists every repository the Rush GitHub App installation can reach, so a script can pick the ones whose root `package.json` has `packageManager` set and no `.devcontainer/` directory. Each run has its own sandbox and its own branch, and a Medusa repository on Yarn or npm gets the same two files with that package manager's install command.

In the console, an automation on the Project with a `github` trigger on `pull_request.opened` and the prompt "if this pull request changes package.json, pnpm-workspace.yaml or apps/backend/.env.template, bring the dev container up from this branch, run the postCreateCommand and comment with its log" keeps the definition honest once it is merged. The trigger adds the pull request after the prompt, only work by an owner, member or collaborator fires it, and the automation's `max_runs_per_hour` bounds a busy day.

## Why run it on Rush?

A dev container that was never started is a guess: the service name in `DATABASE_URL` resolves or it does not, the bind mount owns `node_modules` or it does not, and `postCreateCommand` runs before Postgres answers or after. The agent installs Docker and the Dev Container CLI in its own sandbox, brings the stack up from a clean clone the way a new teammate would, and keeps every command and its output.

The result is a definition built from this repository's own files, the `packageManager` pin, the CORS ports, the migration command in the README and the absence of a Redis module in `medusa-config.ts`, rather than a template copied from another project. The log and the two HTTP responses are in the pull request, and several Medusa repositories can get the same treatment at once, each in its own sandbox.

## Frequently asked questions

### Why no Redis service when the env template has REDIS_URL?

Because `apps/backend/medusa-config.ts` passes only `databaseUrl`, the CORS lists and the two secrets to `defineConfig` and names no Redis-backed module, so the backend runs its event bus and cache in memory. The agent leaves the `REDIS_URL` line alone and says in the description that adding a Redis module to the config is the point at which a service becomes necessary.

### Does it run the migrations automatically?

Yes, in `postCreateCommand`, because the README's setup runs `pnpm medusa db:migrate` right after filling `DATABASE_URL`, and the migration also applies the `migration-scripts` that seed the initial store data. The admin user from the README is not created automatically; the description shows the `pnpm medusa user` command to run once inside the container.

### Will pnpm's build scripts be blocked inside the container?

`pnpm-workspace.yaml` already lists `@medusajs/telemetry` under `onlyBuiltDependencies`, and the container installs with the same pnpm 10.11.1 that `packageManager` pins through corepack, so the install behaves as it does on a laptop. The agent pastes the install summary so a reviewer can see no script was skipped unexpectedly.

### Can the storefront run in the same container?

Yes. Port 8000 is forwarded and `pnpm storefront:dev` works once `apps/storefront/.env` has a publishable key, which the admin issues after the first user exists. Since `AGENTS.md` says `apps/storefront` may not exist, the `postCreateCommand` only copies the storefront's template when the directory is there.

## More Medusa jobs

- [Add a Dockerfile to a Medusa Backend](https://getrush.ai/run/add-dockerfile/medusa/)
- [Add GitHub Actions CI to a Medusa Monorepo](https://getrush.ai/run/add-github-actions-ci/medusa/)
- [Add OpenTelemetry Tracing to a Medusa Backend](https://getrush.ai/run/add-opentelemetry/medusa/)

## The same job on other stacks

- [Add a Dev Container to a Docker Compose Project](https://getrush.ai/run/add-dev-containers/docker-compose/)
- [Add a Dev Container to a .NET Solution](https://getrush.ai/run/add-dev-containers/dotnet/)

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

- [Add a Dead-Letter Queue to a Serverless SQS Worker](https://getrush.ai/run/add-dlq/serverless/)

## 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/)
