What the agent does
The agent reads how the project is installed and started before it writes an image for it. In an app like litestar-org/litestar-hello-world, app.py defines /sync and /async handlers and builds app = Litestar(route_handlers=[...]). pyproject.toml depends on litestar[standard]>=2.4.1, requires Python >=3.8,<4.0, builds with hatchling, declares an app console script pointing at litestar.__main__:run_cli, and keeps ruff, mypy, pytest and pytest-cov in PDM dev groups named lint and test. pdm.lock pins litestar 2.4.1 and uvicorn 0.24.0.post1 with its standard extra. .pre-commit-config.yaml sets default_language_version to Python 3.12 and runs pdm-lock-check, so the lock is kept in step with the manifest. Makefile creates an in-project .venv through pdm config venv.in_project true and pdm install -G:all; README.md starts the app with litestar run --reload or pdm run uvicorn app:app --reload; .github/workflows/ci.yaml tests Python 3.8 through 3.11 with pdm-project/setup-pdm. There is no Dockerfile, no .dockerignore and no container job, and .gitignore already excludes .venv/.
The Dockerfile has two stages so the image carries the virtual environment and not PDM. The builder starts from python:3.11-slim, the newest interpreter the CI matrix tests, installs pdm with pip, copies pyproject.toml and pdm.lock alone, and runs pdm install --prod --no-self --frozen-lockfile with venv.in_project on, so the resolved production dependencies land in /app/.venv from the lock file and nothing else: --prod leaves out the lint and test groups, --no-self skips installing the project itself, which has no package to build, and --frozen-lockfile refuses to re-resolve. The runtime stage starts from the same base, creates an unprivileged user, copies /app/.venv and app.py, puts /app/.venv/bin first on PATH, sets PYTHONDONTWRITEBYTECODE and PYTHONUNBUFFERED, exposes port 8000 and ends with CMD ["litestar", "--app", "app:app", "run", "--host", "0.0.0.0", "--port", "8000"]. The CLI would also find app.py on its own, since app is one of the module names it searches for a Litestar instance, but the explicit --app makes the entry point readable in the file. A .dockerignore keeps .git, .venv, tests, .github, __pycache__ and the cache directories .gitignore lists out of the build context.
The sandbox has no Docker, so the agent installs it (sudo apt-get install -y docker.io, then starts dockerd), builds the image, runs it with port 8000 published, and requests /sync and /async, expecting {"hello": "world"} from both as tests/test_app.py does through TestClient. It checks that the process inside the container runs as the unprivileged user, reads the image size from docker image ls for the pull request, and runs hadolint over the Dockerfile. The app has no dedicated health route, so the HEALTHCHECK it adds requests /sync with Python's urllib rather than curl, which the slim image does not have, and the pull request says that a real service wants a health route of its own.
To keep the image building after the merge, the agent adds a docker job to .github/workflows/ci.yaml that runs docker build . on ubuntu-latest, which has Docker, and starts the container to curl /sync once, beside the existing validate and test jobs. It also adds a short section to README.md with the build and run commands and a make docker-build target in the project's Makefile style. It runs pdm install and pdm run pytest once in the sandbox to show the test suite is untouched, and pre-commit run --all-files so pdm-lock-check and ruff pass on the changed tree.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Write a Dockerfile for this Litestar application. Read pyproject.toml, pdm.lock, app.py, Makefile, README.md, .gitignore, .pre-commit-config.yaml, tests/test_app.py and the workflows under .github/workflows first. Write a two-stage Dockerfile: a builder on a python slim image within the version range the CI matrix tests that installs pdm and runs pdm install --prod --no-self --frozen-lockfile from pyproject.toml and pdm.lock into an in-project .venv, and a runtime stage on the same base that copies the .venv and the application code, runs as a non-root user, exposes port 8000 and starts the app with the litestar CLI bound to 0.0.0.0. Add a .dockerignore and a HEALTHCHECK that uses Python rather than curl. Install Docker in the sandbox, build the image, run it, request /sync and /async and confirm both answer, check the running user and the image size, and run hadolint. Add a docker job to the CI workflow that builds the image and probes it, document the build and run commands in the README, run pytest and pre-commit, and open 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 that adds Dockerfile and .dockerignore, changes .github/workflows/ci.yaml, Makefile and README.md, and touches nothing in app.py or pyproject.toml. The description shows the docker build output, the two JSON responses from the running container, the user the process runs as, the image size as docker image ls printed it, and the hadolint result.
The run's record holds the Docker install, the build, the container start and the probes, plus the pytest and pre-commit runs, so a reviewer can see each step's output instead of reproducing it.
Before merging, a reviewer decides whether to pin the base image by digest as well as tag, whether the litestar run command should take --wc for more than one worker in the deployment, and whether the health check should wait for a dedicated route once one exists. The pull request leaves those as named choices with the line to change for each.
Run it on every Python service without an image
A team with several Litestar or other ASGI services to containerise runs this once per repository from its own server: one POST /o/{org}/sessions per repository, each with that repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started instead of opening a second pull request. Each run installs Docker in its own sandbox and reads that service's own lock file and start command, so a project on Poetry or uv gets the installer it uses.
To keep the image honest afterwards, an automation on the Project with a github trigger on pull_request.opened and pull_request.synchronize and the prompt "if this pull request changes pyproject.toml, pdm.lock or the Dockerfile, build the image, run it, request /sync and comment with the result and the image size" reads each new pull request. The trigger puts the pull request after the prompt; only work by an owner, member or collaborator fires it, never a fork's.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A Dockerfile written without reading the project tends to install from a requirements.txt the project does not have, ship the dev dependencies, run as root and start the wrong module. The agent starts from the lock file and the console script the project already defines, so the image installs exactly what pdm.lock pins and starts the app the way the README does, bound to an address a container can be reached on.
On Rush the build and the probes run in the run's own sandbox, Docker included, and their output is kept with the run, so the pull request carries the responses and the image size it claims. Several services can be containerised at once, each as its own run and its own pull request.
Frequently asked questions
Why install with PDM inside the image rather than exporting requirements.txt?
Because pdm.lock is the project's source of truth and pdm-lock-check in pre-commit keeps it that way. pdm install --frozen-lockfile installs exactly the pinned set with no second resolver. pdm export to a requirements file works too and drops PDM from the builder; the pull request names it as the alternative if the team prefers a plain pip install -r.
Why the litestar CLI and not uvicorn directly?
The CLI is what the project's README and its app console script already use, it runs uvicorn underneath because litestar[standard] is installed, and it adds --wc for workers and --reload for development without a second command to learn. uvicorn app:app --host 0.0.0.0 --port 8000 is the equivalent one-liner, and the pull request shows it for anyone who wants the bare server.
Why Python 3.11 when pre-commit says 3.12?
The pre-commit setting only picks the interpreter that runs the hooks. The CI matrix in ci.yaml tests 3.8 through 3.11, so 3.11 is the newest version the test suite is known to pass on; running the image on 3.12 would ship something CI never ran. The pull request notes that adding 3.12 to the matrix is the step that lets the base image move.
Does the image contain the test and lint tools?
No. --prod excludes the lint and test dev groups, so pytest, ruff, mypy and their dependencies stay out, and --no-self skips the project itself, which is a single module with nothing to package. The runtime stage copies only the virtual environment and app.py; .dockerignore keeps tests/ and the caches out of the build context.