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