What the agent does
The agent reads how the app is configured and run before it writes an image for it. In a repository laid out like reflex-dev/reflex-examples, each of the 26 apps is a directory with its own rxconfig.py, requirements.txt and assets/ folder, and none of them has a Dockerfile, a .dockerignore or a compose file. The basic_crud app declares rx.Config(app_name="basic_crud", db_url="sqlite:///reflex.db", plugins=[rx.plugins.RadixThemesPlugin()]), depends on reflex[db]>=0.9.2 and fastapi, defines a Product SQLModel table in basic_crud/model.py and a product router in basic_crud/api.py that opens rx.session() per request, and its README.md says to run reflex db init and reflex db migrate before reflex init and reflex run. The root .gitignore drops .web, *.db, .states, frontend.zip, backend.zip and assets/external/, and .github/workflows/check_export.yml is the only build the repository has: for every app it creates a venv, installs the requirements with uv pip, sets REFLEX_TELEMETRY_ENABLED to false, runs reflex init then reflex export, and fails if either zip is unreadable or the log mentions a DeprecationWarning.
Reflex's own deployment guide is the second thing the agent reads, because a Reflex app is two processes. reflex run --env prod serves the frontend and backend together on port 3000; split, the backend takes --backend-only --backend-port 8000 and the frontend needs REFLEX_API_URL to find it. The project's docker-example/production image avoids running a Node frontend at all: a python:3.13-slim builder copies uv and bun in, installs requirements.txt into a venv, and runs reflex export --frontend-only --no-zip with REFLEX_API_URL set, which leaves the static frontend in .web/build/client/. The final stage copies that directory to /srv, the venv and .web/backend into /app, installs redis-server and the caddy binary from caddy:2, adds a non-root reflex user whose home is /app so the backend can create .states there, and a Caddyfile on :{$PORT} proxies /_event/*, /ping, /_health and /_upload to localhost:8000 and serves everything else from /srv with the pre-compressed .gz copies the export wrote. Its CMD runs reflex db migrate when an alembic directory exists, starts Caddy and Redis, then exec reflex run --env prod --backend-only.
The agent follows that layout for basic_crud and writes the four files the image needs: Dockerfile, Caddyfile, .dockerignore that excludes .web, venv, *.db, .states, __pycache__ and the two export zips, and a committed alembic/ directory, because the repository has none and the container's reflex db migrate would otherwise have nothing to apply to the SQLite file. It runs reflex db init and reflex db makemigrations in the sandbox to create that directory, pins the uv and bun images by major version as the example does, keeps PORT as a build argument with 8080 as its default, and sets REFLEX_TELEMETRY_ENABLED=false in the image as the export workflow already does. Because the app keeps its data in reflex.db beside the code, the Dockerfile declares /app/data as the place for it, the db_url moves to sqlite:////app/data/reflex.db through an environment variable with the old path as default, and the pull request says to mount a volume there or the products vanish with the container.
The sandbox has no Docker, so the agent installs it first with sudo apt-get install -y docker.io and starts dockerd, then runs docker build -t basic-crud . and docker run -p 8080:8080 with a mounted data directory. It checks GET /ping on the backend route, loads the frontend at /, sends the POST /products and GET /products/1 requests from basic_crud/test.http through the proxied port, confirms the row survives a container restart with the volume and disappears without it, and reads docker image ls for the final size. The check_export.yml matrix is left alone: it lists every top-level directory, and a Dockerfile in basic_crud/ is not a directory, so the job still passes.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Write a Dockerfile for the basic_crud Reflex app in this repository. Read basic_crud/rxconfig.py, basic_crud/requirements.txt, basic_crud/README.md, basic_crud/basic_crud/model.py, basic_crud/basic_crud/api.py, basic_crud/basic_crud/test.http, the root .gitignore and .github/workflows/check_export.yml first, then Reflex's production docker example. Write basic_crud/Dockerfile as a two-stage build: a python slim builder that installs the requirements into a venv with uv and runs reflex export --frontend-only --no-zip with REFLEX_API_URL set from a PORT build argument, and a final stage with Caddy and Redis that serves the exported frontend from /srv, proxies /_event, /ping, /_health and /_upload to the backend on 8000, runs as a non-root user and starts with reflex db migrate followed by reflex run --env prod --backend-only. Add a Caddyfile, a .dockerignore, run reflex db init and reflex db makemigrations and commit the alembic directory so the migration step has something to apply, and move the SQLite file to a /app/data directory configurable through an environment variable. Install Docker in your sandbox, build the image, run it with a volume on /app/data, check /ping and the product routes from test.http, confirm the data survives a restart, and open a pull request with the build output, the responses and the image size. Do not change check_export.yml or any other app.",
"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 basic_crud/Dockerfile, basic_crud/Caddyfile, basic_crud/.dockerignore and the generated basic_crud/alembic/ directory with its first revision, and changes one line of basic_crud/rxconfig.py so db_url reads an environment variable with the old relative path as its default. Its description pastes the docker build output, the /ping response, the product created through the proxied port and read back after a restart, the user the backend runs as, and the image size as docker image ls printed it.
Nothing else in the repository changes: the other 25 apps, check_export.yml and the app's own Python modules are untouched, and the README.md of basic_crud gains a short section with the build and run commands and the volume the data needs.
Before merging, a reviewer decides whether the SQLite volume is what they want or whether db_url should point at Postgres, whether the local Redis in the image should become an external one through REFLEX_REDIS_URL, and whether the pinned uv and bun majors are the ones their other images use.
Run it on every Reflex app without an image
A team with several Reflex apps to containerise sends this body 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 reads its own rxconfig.py: an app with no db_url gets no migration step or data volume, one on Postgres gets the URL passed through unchanged, and one that already commits reflex.lock/ gets that directory copied into the builder as the Reflex docker guide asks.
For a repository of many apps like this one, the same prompt with the app name changed starts one run per app, and each run installs its own Docker in its own sandbox, so the builds do not share a daemon or a port.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A Reflex image written from memory tends to run reflex run in dev mode, ship Node and node_modules in the final layer, bind the frontend to one port and the backend to another with nothing routing between them, and forget that the SQLite file lives in the working directory. The agent starts from the project's own export workflow and Reflex's production example, so the frontend is static, the backend is the only Python process, and the data path is explicit.
The build, the probes and the restart test run in the agent's own sandbox with Docker installed there, and their output is in the pull request. A reviewer reads a build log and three HTTP responses rather than a Dockerfile that looks plausible, and the same run can be started for every app in the repository at once.
Frequently asked questions
Why export the frontend at build time instead of running `reflex run --env prod` for both?
reflex run --env prod serves both halves on one port, but the final image then needs Node or Bun to serve the frontend. Exporting with --frontend-only --no-zip during the build leaves plain HTML, JavaScript and CSS in .web/build/client/, which Caddy serves from /srv, and the final stage carries only the Python venv. That is the layout Reflex's own production example uses.
Why does the pull request add an `alembic` directory?
The example CMD runs reflex db migrate only when an alembic directory exists, and this repository has none; basic_crud/README.md tells a developer to run reflex db init by hand first. The agent runs reflex db init and reflex db makemigrations once in the sandbox and commits the result, so a fresh container creates the product table before the backend starts.
What happens to the products when the container is replaced?
They are in a SQLite file, so they go with the container unless the file is on a volume. The Dockerfile moves it to /app/data and the pull request shows one run where a product survives a restart with a volume mounted and one where it does not. Pointing db_url at Postgres through the new environment variable is the alternative the description names.
Does this change the export workflow?
No. check_export.yml builds its matrix from the top-level directories and runs reflex export in each, and the new files inside basic_crud/ do not change that list. The agent runs that export step itself in the sandbox to confirm the app still exports without a deprecation warning.
Why Caddy and Redis inside the image?
Caddy is the one process that serves the static frontend and proxies the websocket, upload and health routes to the backend, so one port is enough for a platform that exposes one. Redis holds the backend's state, and Reflex's example runs a local one so the container works alone; REFLEX_REDIS_URL is set in the image, so pointing it at a shared Redis is one environment variable.
More Reflex jobs
The same job on other stacks
- Add a Dockerfile to a Rocket App (Rocket)
- Add a Dockerfile to a Sequelize App (Sequelize)
- Write a Dockerfile for a Bolt for JavaScript Slack App (Bolt for JavaScript)