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 with this body:
{
"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"
}
]
}- 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 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.
The use case this job follows, with its automation and trigger: Hand off a long task.
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
The same job on other stacks
- Add a Dev Container to a Docker Compose Project (Docker Compose)
- Add a Dev Container to a .NET Solution (.NET)
More jobs like this: Hand off a long task
- Add a Dead-Letter Queue to a Serverless SQS Worker (Serverless Framework)