# Add a Dev Container to a Docker Compose Project

Yes. An agent adds a .devcontainer that reuses your compose file, runs the services beside an editor container, checks it with the Dev Container CLI and opens a PR.

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

## What the agent does

The agent reads the Compose project before adding anything. In a project like `react-express-mongodb` in docker/awesome-compose, `compose.yaml` defines three services: `frontend`, built from `frontend/Dockerfile` at the `development` target and published on port 3000, `backend`, built from `backend/Dockerfile` at the same target and only exposed on 3000 inside the network, and `mongo` from the `mongo:4.2.0` image with a named volume. Both app services bind-mount their source directory to `/usr/src/app` and mask `node_modules` with an anonymous volume, and two networks keep the browser tier away from the database. The Dockerfiles already have a second stage, `dev-envs`, that installs `git`, creates a `vscode` user and copies the Docker CLI tools in, written for Docker Dev Environments; `backend/package.json` runs `nodemon server.js` as `dev` and has `prettier` scripts, and the frontend is Create React App with `react-scripts`, an `eslintConfig` extending `react-app`, and a `proxy` to `http://backend:3000`.

From that it writes `.devcontainer/devcontainer.json` and `.devcontainer/compose.devcontainer.yaml`. The JSON lists both compose files in `dockerComposeFile`, so the project's own file stays the single source of truth for services, names a new `dev` service as `service`, sets `workspaceFolder` to the repository root mounted at `/workspaces/app`, and sets `remoteUser` to `vscode`, the user the `dev-envs` stage already creates. The override file defines that `dev` service from `backend/Dockerfile` at the `dev-envs` target, mounts the repository root and the Docker socket so the Docker CLI the stage installs can drive the sibling containers, joins both networks so the editor can reach `mongo` and `backend` by name, and runs `sleep infinity` so the container stays up for the editor. `runServices` starts `dev`, `backend`, `frontend` and `mongo` together, `forwardPorts` exposes 3000, and `postCreateCommand` runs `npm ci` in `backend` and `frontend` so the editor's language tools see the dependencies, which the app containers keep in their own anonymous volumes.

Editor settings come from what the repository already uses: `customizations.vscode.extensions` lists the Prettier extension for the backend's `format` and `lint` scripts, ESLint for the frontend's `react-app` config, and the MongoDB extension pointed at `mongodb://mongo:27017` through the compose network. The agent writes nothing into the existing `compose.yaml` and does not change the Dockerfiles, since the stage it needs is already there; the pull request notes that the `node:lts-buster-slim` base is old but out of scope.

The sandbox has no Docker, so the agent installs it first (`sudo apt-get install -y docker.io`, then starts `dockerd`), installs `@devcontainers/cli`, and runs `devcontainer up --workspace-folder .`, which the CLI drives with `docker-compose` when the v2 plugin is absent. Then `devcontainer exec` runs `node --version`, `git --version` and `docker ps` inside the dev container to prove the tools and the socket work, `curl http://backend:3000` from inside shows the Express app answering over the compose network, and `docker-compose ps` output in the description shows all four services up. A `.devcontainer/README.md` explains how to open the folder in VS Code or from the CLI.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add a Dev Container to this Docker Compose project. Read compose.yaml, every Dockerfile, backend/package.json and frontend/package.json first. Write .devcontainer/devcontainer.json that lists the existing compose.yaml plus a .devcontainer override file in dockerComposeFile, names a new dev service built from the existing dev-envs Dockerfile stage with the repository root mounted as the workspace, uses the vscode user that stage creates, mounts the Docker socket, joins the project's networks, starts the app services and the database with runServices, forwards port 3000, runs npm ci in backend and frontend as postCreateCommand, and lists Prettier, ESLint and MongoDB extensions. Do not edit compose.yaml or the Dockerfiles. Install Docker and the Dev Container CLI in the sandbox, run devcontainer up, run node, git and docker commands inside the container with devcontainer exec, request the backend from inside over the compose network, and open a pull request that pastes the service list and those outputs.",
  "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

What comes back is a pull request on its own branch with `.devcontainer/devcontainer.json`, `.devcontainer/compose.devcontainer.yaml` and `.devcontainer/README.md`. `compose.yaml`, both Dockerfiles and both `package.json` files are untouched, so `docker compose up` on its own behaves exactly as before.

The description lists each `devcontainer.json` property and the file it was derived from, the `devcontainer up` output with the four services, the tool versions and `docker ps` from inside the container, and the response from the backend over the compose network. The commands are in the transcript at `GET /o/{org}/sessions/{id}/messages`.

Before merging, a reviewer opens the branch in VS Code with the Dev Containers extension or in a Codespace, checks that the frontend hot-reloads through the bind mount, and decides whether the dev service should move to its own small Dockerfile rather than reusing the backend image, which the pull request raises as an option.

## Run it on every repository with a compose file 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 find the ones with a `compose.yaml` or `docker-compose.yml` and no `.devcontainer/` directory and start a run for each. Each run has its own sandbox and its own branch.

Give the key a `webhook_url` and each run POSTs `run.completed` with its `session_url` when the turn finishes, so the pull request links collect on your side without polling. A key may have at most `max_concurrent` runs in progress at once, 4 by default, and starting one more answers `202` with `status: "queued"`, so a script over many repositories sends every request up front and Rush starts each waiting run as one finishes.

## Why run it on Rush?

A Dev Container over Compose fails in ways a laptop hides: the editor container is not on the network the database uses, the workspace mount shadows the `node_modules` volume, the user in the image does not own the files. In a Rush sandbox the agent installs Docker and the Dev Container CLI, brings the whole stack up with the real images and runs commands inside the container, so the configuration you review has already started and answered a request over the compose network.

The result is a configuration that reuses what the repository has, the compose file and the `dev-envs` stage, instead of a parallel definition that drifts, with the proof in the transcript beside the commands. Several repositories can be onboarded at once, each in its own sandbox and pull request.

## Frequently asked questions

### Does this change how docker compose up works?

No. The existing `compose.yaml` is not edited; the Dev Container adds a second compose file layered on top only when the editor starts it. Running `docker compose up` from the repository root starts the same three services as before.

### Why reuse the dev-envs stage instead of a devcontainer image?

The stage already exists in both Dockerfiles, creates the `vscode` user and installs `git` and the Docker CLI, so it is the smallest change that gives the editor what it needs. The pull request notes that a dedicated small image is an option if the team prefers not to build the backend image for the editor.

### Will installs in the editor conflict with the app containers?

No. The app containers keep `node_modules` in their anonymous volumes as the compose file already arranges, and the `postCreateCommand` installs into the bind-mounted workspace for the editor's language tools. The two never share a directory, and `npm ci` in the editor is reproducible from the lockfiles.

### Does it work in GitHub Codespaces?

Yes. Codespaces reads the same `devcontainer.json` and the compose files it references. The Docker socket mount works there as well, and `forwardPorts` is what makes port 3000 appear in the Codespace's ports view.

## More Docker Compose jobs

- [Move Compose Passwords into Docker Secrets](https://getrush.ai/run/add-docker-secrets/docker-compose/)
- [Move Hard-Coded Values in a Compose File into a .env File](https://getrush.ai/run/add-env-file/docker-compose/)
- [Add Hadolint to CI for a Docker Compose Repository](https://getrush.ai/run/add-hadolint-to-ci/docker-compose/)

## The same job on other stacks

- [Add a Dev Container to a .NET Solution](https://getrush.ai/run/add-dev-containers/dotnet/)
- [Add a Dev Container to a Medusa Monorepo](https://getrush.ai/run/add-dev-containers/medusa/)

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