What the agent does
The agent clones the repository into its own cloud sandbox and reads the app's shape before adding a route. In the default template of remix-run/react-router-templates, app/routes.ts holds a single index('routes/home.tsx'), react-router.config.ts keeps ssr: true, app/root.tsx provides the Layout, an ErrorBoundary built on isRouteErrorResponse and the Inter font links, and routes/home.tsx renders the Welcome component with a meta export. package.json runs react-router dev, react-router build and react-router-serve ./build/server/index.js, with typecheck as react-router typegen && tsc; it depends on @react-router/node, @react-router/serve, isbot and React 19, with Vite 8, Tailwind 4 and TypeScript 5.9 as dev dependencies. tsconfig.json maps ~/* to app/* and includes the generated .react-router/types, and the Dockerfile builds on node:24-alpine with npm ci.
For the upload itself the agent uses the packages the React Router file-upload guide names: @remix-run/form-data-parser, whose parseFormData streams each file to an upload handler instead of buffering the whole body, and @remix-run/file-storage, whose LocalFileStorage keeps files on disk under a key. It adds app/uploads.server.ts, with the .server suffix that keeps it out of the client bundle, exporting a LocalFileStorage rooted at ./uploads and a getStorageKey helper; a routes/upload.tsx with a form using encType="multipart/form-data" and an action that calls parseFormData with a handler accepting only the file field, only image types, and a size limit the parser enforces while streaming; and a resource route routes/files.$key.tsx whose loader streams the stored file back with its Content-Type.
app/routes.ts gains the two routes, and the generated ./+types/upload and ./+types/files.$key types give the action and loader typed params and formData. The agent adds uploads/ to .gitignore and .dockerignore, and leaves a comment in uploads.server.ts that the container's disk is ephemeral, so a deployment that keeps files across restarts should swap in another FileStorage implementation behind the same two functions. The error boundary in root.tsx already renders thrown Response objects, so a rejected file becomes a readable 400 or 413 page.
Proof follows the template's own checks: npm run typecheck, npm run build, then npm run start in the sandbox while the agent opens the page in its browser, uploads a small image, follows the returned link and confirms the bytes come back with the right type, and tries a text file to see the rejection. It runs the Dockerfile build to confirm the new dependencies install with npm ci, and opens a pull request that links back to the issue.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "A Linear issue labeled agent says: \"Users need to upload an image and get a link to it. Add an upload page that accepts one image, stores it on the server and serves it back by URL.\" Do the work in this React Router app in framework mode. Read package.json, app/routes.ts, react-router.config.ts, app/root.tsx, tsconfig.json and the Dockerfile first. Use @remix-run/form-data-parser so the body streams to an upload handler, and @remix-run/file-storage with LocalFileStorage behind a .server module, add a resource route that streams the stored file back with its content type, reject non-image fields and oversized files, add the storage directory to .gitignore and .dockerignore, run typecheck and build, exercise the page in a browser, and open a pull request that links back to the issue.",
"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 links to the issue. The diff adds app/uploads.server.ts, app/routes/upload.tsx, app/routes/files.$key.tsx, two entries in app/routes.ts, the two packages in package.json and the lockfile, and the ignore entries. The description shows the form, the action's checks and the URL shape a stored file gets.
The run's record keeps the typecheck and build output, the server log for the upload and the download, and the browser screenshots of the page, the served image and the rejection, so a reviewer can see the flow without running the app.
Before merging, a reviewer checks the size limit and accepted types against the product need, decides where files should live in production, since LocalFileStorage writes to the container's disk, and confirms the resource route does not let a crafted key read outside the storage directory, which is why keys are generated rather than taken from the file name.
Run it on every Linear issue labeled agent
Create an automation with a linear trigger for the label your team uses to hand work to an agent, in the Project that holds the repository; it appends each labeled issue to this prompt and starts one run per issue, each with its own sandbox and pull request. From your own server, start the same run with POST /o/{org}/sessions, putting the issue URL https://linear.app/<workspace>/issue/<ID> in resources next to the repository so its text is read through your Linear connection.
With a webhook URL on the API key, every run that key starts posts run.completed or run.failed carrying the session_url, which a small handler can turn into a comment on the issue with the pull request link. Include a request_id in the body so a retried request returns the run already started.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
File upload code is only trustworthy once a real browser has sent a real multipart body through it, and once the oversized and wrong-type cases have been tried. The sandbox builds the app, serves it and drives the page in a browser, keeping the server log and screenshots, so the pull request carries that evidence.
The guide's packages change the action's shape from request.formData() to a streaming handler, and getting the generated route types, the .server boundary and the Docker build right together is fiddly. One run does all of it and proves it, and the same prompt runs against several React Router apps at once, each in its own sandbox.
Frequently asked questions
Why not just call request.formData()?
request.formData() reads the whole body into memory before the action sees a byte. parseFormData hands each file to the upload handler as it streams, so the action can store it immediately, cap its size and reject it early, which is why the React Router guide uses it.
Where do the files go in production?
LocalFileStorage writes under ./uploads on the server's disk, which the Dockerfile's container loses on redeploy. The storage module exposes two functions, so swapping in another FileStorage implementation, or a bucket, is a one-file change the pull request points out.
Does it work in SPA mode?
No. Actions and loaders run on the server, and the guide applies to framework mode with ssr: true, which this template already sets. A SPA would post to a separate API instead.
Is the file name used in the URL?
No. The storage key is generated in the action, and the resource route looks files up by that key only, so a client cannot choose a path. The original name is kept in the stored File for the Content-Disposition header.
More React Router jobs
The same job on other stacks
- Add File Uploads to a Reflex Chat App (Reflex)
- Add File Uploads to a Vapor API (Vapor)
- Add File Uploads to an AdonisJS App (AdonisJS)