What the agent does
The agent reads the build and the routing before it adds a plugin, because Ktor's rate limiter is a separate artifact and its version comes from the Gradle plugin. In an API shaped like the postgres sample of ktorio/ktor-samples, build.gradle.kts applies io.ktor.plugin 3.6.0 with Kotlin 2.4.20 and a JVM 17 toolchain, and depends on ktor-server-core-jvm, ktor-server-content-negotiation-jvm, ktor-serialization-kotlinx-json-jvm, ktor-server-netty-jvm, ktor-server-config-yaml and the postgresql 42.7.8 driver, with ktor-server-test-host-jvm and kotlin-test-junit for tests. src/main/resources/application.yaml names the module com.example.PostgresApplicationKt.module on port 8080. PostgresApplication.kt calls configureSerialization() and configureRouting(dbConnection = connectToPostgres(embedded = false)), and plugins/Routing.kt defines POST /articles, GET /articles/{id}, PUT /articles/{id} and DELETE /articles/{id} over an ArticleService that runs plain JDBC statements.
It adds implementation("io.ktor:ktor-server-rate-limit") to build.gradle.kts, unversioned like the other Ktor artifacts so the plugin's BOM pins it. A new plugins/RateLimiting.kt installs RateLimit with two providers: global for every request and a named writes provider for the mutating routes, each with rateLimiter(limit, refillPeriod) read from a new ratelimit block in application.yaml so the numbers are configuration, not constants. In Routing.kt the POST, PUT and DELETE routes move inside rateLimit(RateLimitName("writes")) { ... } and the GET stays under the global limit only. The key is the client address from call.request.origin.remoteHost, which the pull request notes should become the forwarded address behind a proxy, with the ForwardedHeaders plugin.
The sample has no tests of its own, so the agent writes the first one in the shape the jwt-auth-tests sample uses: src/test/kotlin/com/example/RateLimitTest.kt with testApplication, MapApplicationConfig to set a limit of two per minute, and the test client. Because module() opens a JDBC connection, the test calls configureSerialization(), configureRateLimiting() and configureRouting() with a stub Connection rather than the Postgres from docker-compose.yaml. It sends three POST /articles and asserts the third is 429 Too Many Requests with Retry-After and X-RateLimit-Remaining: 0, then sends three GET /articles/1 and asserts none is 429.
Before pushing, the agent runs ./gradlew clean check --console=plain, the command build-all.sh and the Build All Samples workflow run for every sample, with the Gradle 9.2.1 wrapper the repository ships, and pastes the test report. It also starts the app once with the docker-compose.yaml Postgres and shows a curl loop hitting POST /articles until the 429 appears.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add rate limiting to this Ktor API and open a pull request. Read build.gradle.kts, gradle.properties, src/main/resources/application.yaml, src/main/kotlin/com/example/PostgresApplication.kt, src/main/kotlin/com/example/plugins/Routing.kt, src/main/kotlin/com/example/service/ArticleService.kt and docker-compose.yaml first. Add io.ktor:ktor-server-rate-limit to build.gradle.kts, unversioned like the other Ktor artifacts. Add plugins/RateLimiting.kt that installs RateLimit with a global provider and a named writes provider, both with limit and refill period read from a ratelimit block in application.yaml, keyed by the client address. Wrap POST, PUT and DELETE /articles in rateLimit(RateLimitName(\"writes\")) and leave GET under the global limit. Add src/test/kotlin/com/example/RateLimitTest.kt using testApplication and MapApplicationConfig with a limit of two: three POST /articles return 429 on the third with Retry-After and X-RateLimit-Remaining headers, three GET /articles/1 never return 429. Use a stub java.sql.Connection in the test instead of Postgres. Run ./gradlew clean check --console=plain and paste the output in the pull request, then start the app with the docker-compose Postgres and show a curl loop reaching the 429. Do not change ArticleService or the existing route paths.",
"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 with one new dependency in build.gradle.kts, plugins/RateLimiting.kt, a ratelimit block in application.yaml, the rateLimit wrapper around the three write routes in Routing.kt, a call to configureRateLimiting() in PostgresApplication.kt, and src/test/kotlin/com/example/RateLimitTest.kt. The description shows the Gradle test report, the 429 response with its headers from the curl loop, and the limits chosen.
On a repository with the Build All Samples workflow, the pull request triggers ./build-all.sh, which runs ./gradlew clean check for the sample on JDK 24, so the new test runs on the pull request. The detekt workflow scans the new Kotlin file too.
A reviewer checks that the limiter is keyed by client address and that the key will be the forwarded address once ForwardedHeaders is installed behind a proxy, that GET reads are not throttled by the writes provider, that the limits in application.yaml match what the service can take, and that the 429 carries Retry-After so clients can back off. Then they set production values in the deployment's config.
Run it on every service exposed to the public internet
A team with several Ktor services sends one POST /o/{org}/sessions per repository with this prompt and that repository in resources. Each run reads its own Routing.kt, so a service with an authenticated /login route gets a tighter named provider on it, and each run opens its own pull request.
Give the API key a webhook_url and Rush POSTs run.completed when each turn ends, with the session_url to read the pull request from, so the chosen limits can be reviewed across services at once.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Rate limiting is cheap to add and easy to get wrong: throttling reads along with writes, keying by the proxy's address, or choosing a limit no one ever tested. In a Rush sandbox the agent installs the plugin against the pinned Ktor 3.6.0, writes the testApplication case, runs the Gradle wrapper the repository ships, and keeps every command and the 429 response in the run's record, so the pull request shows the limiter working.
The sample has no test suite today, and a first test is the part most people skip. The agent writes it in the style the sibling jwt-auth-tests sample uses, so the next contributor has a pattern to follow, and the same request works unchanged on every Ktor service a team owns.
Frequently asked questions
Does it add a dependency?
One: io.ktor:ktor-server-rate-limit, a first-party Ktor artifact pinned by the io.ktor.plugin BOM already in build.gradle.kts, so no version string is added.
Why two providers?
Reads are cheap and writes hit Postgres through ArticleService, so they get different budgets. The global provider protects every route, and the named writes provider wraps POST, PUT and DELETE /articles with a smaller limit.
How does the test avoid Postgres?
module() opens a JDBC connection, so the test calls the plugin functions directly with a stub java.sql.Connection whose statements return nothing. The 429 comes from the plugin before the handler runs, so the stub is never exercised for the throttled request.
What about requests behind a load balancer?
The limiter keys by call.request.origin.remoteHost, which behind a proxy is the proxy. The pull request notes that installing Ktor's ForwardedHeaders plugin makes remoteHost the client address, but leaves that for the reader because trusting forwarded headers depends on their network.
More Ktor jobs
The same job on other stacks
- Add Rate Limiting to a LangGraph Agent (LangGraph)
- Add Rate Limiting to a Leptos Server (Leptos)
- Add Rate Limiting to a Litestar API (Litestar)