What the agent does
The agent reads what the image has to carry before it writes it. In an app like filamentphp/demo, composer.json asks for php ^8.1 but both workflows in .github/workflows set up PHP 8.4, and the Laravel Boost guidelines in CLAUDE.md name 8.4 too, so that is the runtime. tests.yml is the clearest list of what the app needs: PHP with mbstring, pdo and pdo_sqlite, Node 20 for npm ci && npm run build, a copied .env.example, php artisan key:generate, a touch database/database.sqlite, and composer test:pest, which composer.json defines as pest --parallel. .env.example sets DB_CONNECTION=sqlite, CACHE_DRIVER=file, SESSION_DRIVER=file and QUEUE_CONNECTION=sync, so the app needs no database server and no queue worker to run. vite.config.js builds app.css, app.js and the Filament admin theme with Tailwind 4, and laravel/octane is already in require, with config/octane.php defaulting OCTANE_SERVER to roadrunner and .gitignore already listing FrankenPHP's files.
From that it writes a three-stage Dockerfile. A Node 20 stage runs npm ci and npm run build so the hashed assets land in public/build. A Composer stage runs composer install --no-dev --prefer-dist --optimize-autoloader --no-scripts against composer.lock, then runs php artisan package:discover and php artisan filament:upgrade itself, the two commands the post-autoload-dump script would have run, once the application code is copied in. The runtime stage starts from a PHP 8.4 image, installs the extensions composer check-platform-reqs lists plus pdo_sqlite and the image library the media library's conversions use, copies vendor/ and public/build from the earlier stages, and ships no Node, Composer or dev dependency. Because Octane is already installed, the agent serves the app with php artisan octane:start --server=frankenphp --host=0.0.0.0 from a FrankenPHP base image, and says in the pull request what to change for php-fpm behind nginx instead.
A small entrypoint does on first boot what composer setup does on a laptop: it creates database/database.sqlite when it is missing, runs php artisan migrate --force, runs php artisan db:seed only when SEED=1 because the seeders in database/seeders load demo data and local images, and runs php artisan storage:link so the media library's public disk is reachable. compose.yaml has one app service on port 8000 with APP_KEY passed from the environment, and two named volumes, one for storage/ and one for database/, so uploads and the SQLite file survive a rebuild. A .dockerignore keeps vendor/, node_modules/, .env, storage/logs and public/build out of the build context.
Then it proves the thing boots. The sandbox has no Docker preinstalled, so the agent installs it with sudo apt-get install -y docker.io, starts dockerd, and uses docker-compose v1 from that package set, since Compose v2 is not in it. It builds the image, starts the stack with SEED=1, opens the /admin login page in the sandbox's browser, signs in with the admin@filamentphp.com account the README documents, takes a screenshot of the dashboard with its seeded widgets, and uploads a product image to show the storage volume works. On the host checkout it runs composer test:pest and composer test:phpstan too, so the pull request shows no PHP file changed behaviour.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Dockerize this Filament app. Read composer.json, composer.lock, package.json, vite.config.js, .env.example, config/octane.php, the workflows in .github/workflows and the README first, and take the PHP version from CI rather than the composer floor. Write a multi-stage Dockerfile: a Node stage that builds the Vite assets, a Composer stage that installs production dependencies and then runs the package:discover and filament:upgrade commands from the post-autoload-dump script, and a PHP runtime stage with the extensions composer check-platform-reqs lists plus pdo_sqlite and the image library the media library needs. Serve with Octane on FrankenPHP since Octane is already installed, and explain the php-fpm alternative in the PR. Add an entrypoint that creates the SQLite file, migrates, seeds only when SEED=1 and runs storage:link; a compose.yaml with named volumes for storage and the database and APP_KEY from the environment; and a .dockerignore. Install Docker in the sandbox, build and start the stack, log in to /admin with the account the README documents, screenshot the dashboard, run composer test:pest and composer test:phpstan, and open a pull request with the commands and the screenshot.",
"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 Dockerfile, compose.yaml, .dockerignore, docker/entrypoint.sh and a Docker section in the README. No PHP, Blade or JavaScript file changes. The description lists each choice and the file it came from: PHP 8.4 from tests.yml, the extensions from composer check-platform-reqs, SQLite from .env.example, FrankenPHP from the Octane dependency already in composer.json, and the two volumes from where the media library and the database write.
The record is in the transcript at GET /o/{org}/sessions/{id}/messages: the Docker install, each docker build including any attempt that failed before a fix, the container logs with the migration and seed output, the browser login and the dashboard screenshot, the image size from docker image ls, and the Pest and PHPStan runs. The repository's own tests and phpstan workflows run on the pull request as before, since the application code is unchanged.
Before merging, a reviewer checks that APP_KEY comes from a secret and not the compose file, that the storage/ volume is backed up wherever the container runs, and whether production should use MySQL or Postgres rather than the SQLite file, which the README's composer setup flow and CI both use. One follow-up message to the same session adds a database service and the DB_* variables if so.
Run it on every new Laravel service without a Dockerfile
A developer starts one run from the terminal with this prompt and the repository when a service needs to run somewhere other than a laptop, and gets the pull request back with the screenshot of the panel served from the container. The sandbox parks when the turn ends, so a follow-up that swaps SQLite for Postgres wakes it with the image already built.
A platform team can send one POST /o/{org}/sessions per repository. GET /o/{org}/github lists the repositories the Rush GitHub App installation reaches, and a script starts a run only where no Dockerfile exists. Each run reads that app's own CI, extensions and drivers, so two Filament apps get two different Dockerfiles.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A Dockerfile copied from a blog post fails on the first extension the media library needs or the first Octane flag that does not match the server. The agent reads the workflows, composer.json and the environment file, runs composer check-platform-reqs against the real lock file, and then installs Docker in its own sandbox and builds the image until the admin panel loads with seeded data, which is the only test that matters for this job.
The pull request carries its own proof: the build log, the container logs, the browser screenshot of the dashboard and the Pest run are in the transcript beside the commands that produced them. Several repositories can be handled at once, each in its own sandbox with its own Docker daemon.
Frequently asked questions
Why FrankenPHP and Octane rather than php-fpm and nginx?
Because laravel/octane is already in the app's require and .gitignore already lists FrankenPHP's files, so the team has run it that way before. The pull request explains the php-fpm variant with nginx in front for teams that prefer it, and the entrypoint and volumes are the same either way.
Does the image seed the demo data?
Only when SEED=1 is set, because the seeders load demo records and local images that a production deployment does not want. The entrypoint always migrates and links storage; seeding is a one-time choice the README documents.
Is SQLite the right database in a container?
It is what .env.example, composer setup and CI use, so the first image matches how the app is tested today, with the file on a named volume so it survives a rebuild. For MySQL or Postgres, a follow-up adds the service and the DB_* variables; the pdo_mysql or pdo_pgsql extension is the only image change.
Will dev dependencies end up in the image?
No. The Composer stage installs with --no-dev, the Node stage exists only to build public/build, and the runtime stage copies vendor/ and the built assets from them. Pest, PHPStan, Pint, Rector and Sail stay out, and the .dockerignore keeps a local vendor/ and node_modules/ out of the build context.
More Filament jobs
The same job on other stacks
- Dockerize a Gin API (Gin)
- Dockerize a Hono App Running on Bun (Hono)
- Dockerize a Ktor Server (Ktor)