What the agent does
The agent clones the repository into its own cloud sandbox and maps every build context before it writes an ignore file. In an application like dockersamples/example-voting-app, docker-compose.yml builds four images from four directories: ./vote (with target: dev), ./result, ./worker and ./seed-data, and the three GitHub workflows under .github/workflows/call-docker-build-*.yaml pass context: vote, result and worker to a reusable build workflow. Only one context has an ignore file: result/.dockerignore, which lists node_modules/. Each Dockerfile copies the whole context at some point: vote/Dockerfile runs COPY . . in its final stage after installing requirements.txt, result/Dockerfile runs COPY . . after npm ci, worker/Dockerfile copies *.csproj for the restore and then COPY . . for dotnet publish, and seed-data/Dockerfile copies everything and runs make-data.py.
It then looks at what actually sits in those directories after a normal development session, not just in git: vote/ collects __pycache__/ and a .venv when someone runs the app locally, result/ has the node_modules/ the existing ignore already covers plus npm-debug.log files, worker/ grows bin/ and obj/ from any local dotnet build, which the multi-stage build would otherwise copy into the publish stage and which can shadow the restored packages, and seed-data/ keeps the generated postdata files that make-data.py writes. The agent also checks for files that are in git but have no place in an image: each directory's Dockerfile itself, and the .dockerignore it is about to add.
For each context it writes a .dockerignore that names those paths and the usual editor and OS files, keeps the existing node_modules/ line in result/, and deliberately does not ignore anything the Dockerfile needs: requirements.txt, package*.json, Worker.csproj, make-data.py and generate-votes.sh all stay. It writes nothing at the repository root, because no build uses the root as its context, and says so in the pull request rather than adding a file that would never be read. Where a COPY . . could be narrowed to the few files the stage needs, it leaves that as a note, since the job is the ignore file and not a Dockerfile rewrite.
To prove the images are unchanged and the contexts smaller, it installs Docker in the sandbox (sudo apt-get install -y docker.io, then starts dockerd), generates the local clutter each directory would have (a dotnet build in worker/, a pip install into a .venv in vote/, npm install in result/), and builds every image twice, before and after the ignore files, with --progress=plain so the transferring context line reports the bytes sent. It compares the image layers with docker history and the file lists with docker run --rm <image> find /usr/local/app or /app, so the only differences are files that should never have been there. Those before-and-after numbers go in the pull request.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add a .dockerignore to every Docker build context in this repository. First list each context from the compose files and the CI workflows and read its Dockerfile to see what each COPY needs. For each context write a .dockerignore that excludes build output, dependency folders, caches, editor and OS files and the Dockerfile itself, without excluding anything a COPY or RUN step reads; keep any existing entries. Do not add a root .dockerignore if no build uses the root as context. Install Docker in the sandbox, create the typical local build artifacts in each directory, build every image before and after with plain progress output, and report the context size sent and the image file list differences per context in a pull request.",
"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 that adds vote/.dockerignore, worker/.dockerignore and seed-data/.dockerignore and extends result/.dockerignore. The description has one table row per context: the Dockerfile's COPY lines, what the ignore file excludes, the transferring context bytes before and after from the sandbox builds, and the list of files that no longer land in the image, which should be only caches and build output.
The run's record keeps every docker build with its plain progress output and the find listings from inside the images, so a reviewer can check that requirements.txt, package.json, the .csproj and the seed scripts are still copied and the applications still start.
Before merging, a reviewer decides whether to go further and narrow the COPY . . lines the agent flagged, and whether the CI workflows should fail when a build context grows past a size, now that there is a baseline number per image.
Run it on every new Dockerfile in the repository
In the console, an automation in the Project that has the repository, with a github trigger on pull_request.opened and pull_request.synchronize and branch_patterns for your default branch, starts one run per pull request, with the pull request as its context. Its prompt asks the run to comment with a proposed .dockerignore when the pull request adds a Dockerfile in a directory that has none, and to stop otherwise; the saved prompt is the whole instruction and the trigger fills in no placeholder.
For a sweep of many repositories, a script sends one POST /o/{org}/sessions per repository with this body, each with a fresh UUID as request_id so a retry returns the run already started. Each run finds that repository's own contexts from its compose files and workflows, so a repository that builds from the root gets a root file and one that builds per service gets one per service.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A missing ignore file costs a little on every build and a lot on the one day a local bin/ or .venv ends up inside a published image. Writing the file is quick; knowing it excludes nothing a COPY needs is the part that takes a build, and the agent runs the builds in its sandbox with the clutter deliberately present and shows the file lists before and after.
The sandbox is its own computer, so installing Docker, building four images twice and diffing their contents leaves nothing on your machine and keeps every command and number in the run's record. Several repositories can be swept at once in separate sandboxes, each with its own pull request.
Frequently asked questions
Could the ignore file break a build?
Only by excluding a path a COPY or a build step reads, which is why the agent reads every Dockerfile first and then builds each image after the change and lists the files inside it. The pull request shows that the dependency manifests and the application sources are still copied.
Why no .dockerignore at the repository root?
An ignore file is read from the build context's root, and in this repository every build uses a service directory as its context, so a root file would never apply. The pull request says this explicitly so nobody adds one later expecting it to work.
Does ignoring the Dockerfile itself matter?
The build reads the Dockerfile before the context is sent, so excluding it from the context changes nothing about the build and keeps it out of the image's COPY . . layer. It is a small tidy-up the agent includes because it costs nothing.
Will CI builds get faster?
The context on a CI runner is a fresh checkout, so it has none of the local clutter and the saving there is small. The numbers in the pull request come from a sandbox that mimics a developer machine, which is where the large contexts and the accidental files come from.