# Add File Uploads to a Vapor API

Yes. An agent adds a multipart upload route, a Fluent model and migration for stored files, a writable uploads directory and tests to your Vapor app, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-file-uploads/vapor/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent clones the API into its own cloud sandbox and reads the whole project before it adds a route. In a Vapor app like vapor/template-fluent-postgres, `Package.swift` uses Swift tools 6.3 and depends on `vapor` from 4.121.4, `fluent` from 4.13.0 and `fluent-postgres-driver` from 2.12.0, with upcoming features such as `ExistentialAny` and `MemberImportVisibility` enabled for every target. `configure.swift` builds the Postgres connection from `DATABASE_HOST`, `DATABASE_PORT`, `DATABASE_USERNAME`, `DATABASE_PASSWORD` and `DATABASE_NAME`, registers the `CreateTodo` migration, and keeps `FileMiddleware` commented out. `routes.swift` registers `/`, `/hello` and `TodoController`, which serves `GET` and `POST /todos` and `DELETE /todos/:todoID` over a `Todo` model with a single `title` field.

Uploads attach to what the app already has. The agent writes an `Attachment` model with an `@Parent` reference to `Todo`, the original filename, the content type, the byte count, the stored path and a `created_at` timestamp, plus a `CreateAttachment` migration that adds the `attachments` table with a foreign key to `todos` set to cascade on delete, and a `@Children` property on `Todo` so a todo's files can be loaded with it. The route is `POST /todos/:todoID/attachments`, decoding a multipart form with a `File` field through `req.content`, and `GET /todos/:todoID/attachments` lists what was stored. Because `req.content` buffers the body, the agent raises `app.routes.defaultMaxBodySize` to the limit named in the prompt and rejects a larger body with 413 before reading it.

Where the bytes go is the part that decides whether this works in production. `Dockerfile` copies `Public/` into the image and marks it read-only with `chmod -R a-w`, and runs the binary as the `vapor` user, so the agent does not write uploads under `Public/`. It reads an `UPLOADS_DIR` variable in `configure.swift`, defaulting to an `Uploads/` directory under the working directory, creates it at startup, and adds an `uploads_data` volume mounted at `/app/Uploads` to the `app` service in `docker-compose.yml`, beside the existing `db_data` volume. Stored files are named by the attachment's UUID with the client's filename kept only in the database, so a path in a filename cannot escape the directory, and `GET /attachments/:attachmentID` streams a file back with `req.fileio.streamFile` and the recorded content type. `Uploads/` joins `.gitignore`.

Tests follow the suite that exists. `Tests/TemplateFluentPostgresTests` uses Swift Testing with a serialized suite and a `withApp` helper that runs `autoMigrate` before each test and `autoRevert` after it, so the new migration is exercised on every run. The agent adds tests that create a todo, post a small multipart body with `req.content.encode(_:as: .formData)`, assert a 201 and a stored row, download the file and compare the bytes, post a body over the size limit and assert 413, and delete the todo and assert its attachments are gone. It starts Postgres with `docker compose up db`, runs `swift test`, and runs `swift build` once more so the warnings-as-errors settings in `Package.swift` are honoured.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add file uploads to this Vapor API. Read Package.swift, Sources/*/configure.swift, routes.swift, the Todo model, DTO, migration and controller, Dockerfile, docker-compose.yml and the tests first. Add an Attachment model with a parent reference to Todo (original filename, content type, size, stored path, created_at) and a CreateAttachment migration with a cascading foreign key, and register it in configure.swift. Add POST /todos/:todoID/attachments taking a multipart form with a File field, GET /todos/:todoID/attachments listing them, and GET /attachments/:attachmentID streaming the bytes back with the stored content type. Store files under a directory read from UPLOADS_DIR, defaulting to Uploads/ in the working directory, named by the attachment id, never under Public/, and add an uploads volume for the app service in docker-compose.yml plus Uploads/ in .gitignore. Set defaultMaxBodySize to 10mb and answer 413 above it. Add Swift Testing tests in the existing suite for upload, list, download, oversize and cascade on todo delete. Start Postgres with docker compose up db, run swift test and swift build, and open a pull request that lists the routes, the migration and the test results.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **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.
2. **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.
3. **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 adding `Models/Attachment.swift`, `Migrations/CreateAttachment.swift`, an `AttachmentDTO`, an `AttachmentController` registered in `routes.swift`, the `UPLOADS_DIR` handling and migration registration in `configure.swift`, the volume in `docker-compose.yml`, the `.gitignore` line and the new tests. `Todo.swift` gains a `@Children` property and `TodoDTO` is unchanged unless the prompt asks for attachment counts in the list response.

The description names each route with its request and response shape, the body size limit and where it is enforced, the storage directory and why `Public/` was not used, and the `swift test` summary. The transcript at `GET /o/{org}/sessions/{id}/messages` keeps the `docker compose up db`, `swift build` and `swift test` output, so the reviewer can see the migration run and every test pass rather than read a sentence saying so.

Before merging, a reviewer checks that the stored path never includes client input, that the migration's `revert` drops the table, and that the volume name matches the mount in the Dockerfile's working directory. A follow-up on the same session can swap the local directory for an S3-compatible store or add an allow-list of content types.

## Run it on every Linear issue labelled agent

Add an automation to the Project with this prompt and a `linear` trigger on `linear.issue.labeled`, filtered to the `agent` label. When someone labels an issue such as "attach receipts to a todo", the trigger places the issue after the prompt, the run reads which model the issue wants files on, and the pull request links back to the issue. Only label changes made by a person in your Rush org fire the trigger, and the automation starts at most `max_runs_per_hour` runs in an hour.

From a script, the same body goes to `POST /o/{org}/sessions` with the repository in `resources` and the issue URL as a second resource, so the issue text is in the prompt; a `request_id` that is a UUID v5 of the issue id makes a retry safe. Give the key a `webhook_url` and each run the key starts posts `run.completed` with `data.session_url`, from which a handler reads the pull request link.

## Why run it on Rush?

A file upload route is easy to write and easy to get subtly wrong: a body buffered with no limit, a filename used as a path, a directory that is read-only inside the container. The agent reads the Dockerfile and the compose file before it chooses a directory, and it proves the limit and the cascade with tests that run against a real Postgres in its own sandbox, with Docker and a Swift 6.3 toolchain already there.

Every command and its output stay in the run's transcript, so the review is of a `swift test` log rather than of a promise, and the laptop that started the run is free while the toolchain compiles. Several services can get the same route at once, each in its own sandbox and its own pull request.

## Frequently asked questions

### Why not serve uploads from the Public directory with FileMiddleware?

Because the template's `Dockerfile` copies `Public/` into the image and makes it read-only, so a running container cannot write there, and anything placed under `Public/` is served to anyone who guesses the name. The agent stores files in a separate directory backed by a volume and serves them through a route it controls.

### What is the maximum upload size?

Whatever the prompt sets; the example uses 10 MB through `app.routes.defaultMaxBodySize`. The limit is enforced before the body is read, so an oversize request is refused with 413 instead of being buffered, and a test posts a body over the limit to prove it.

### Does it change the existing todo routes?

No. `GET`, `POST` and `DELETE /todos` keep their request and response shapes and the existing tests keep passing. The only change to `Todo` is a `@Children` property, and the only change to deletion is that a todo's attachments go with it through the migration's cascading foreign key.

### Can the files go to object storage instead of disk?

Yes, as a follow-up. The route and the model do not depend on where bytes are written, so a message on the same session can replace the local directory with an S3-compatible client while keeping the routes, the migration and the tests.

## More Vapor jobs

- [Set Up GitHub Actions CI for a Vapor App](https://getrush.ai/run/add-github-actions-ci/vapor/)
- [Add Health Checks to a Vapor App](https://getrush.ai/run/add-health-checks/vapor/)
- [Add Request Validation to a Vapor API](https://getrush.ai/run/add-input-validation/vapor/)

## The same job on other stacks

- [Add File Uploads to an AdonisJS App](https://getrush.ai/run/add-file-uploads/adonisjs/)
- [Add File Uploads to a CodeIgniter 4 App](https://getrush.ai/run/add-file-uploads/codeigniter/)
- [Add File Uploads to a Livewire Component](https://getrush.ai/run/add-file-uploads/livewire/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
