# Add a Custom Domain to a Serverless Framework API

Yes. An agent puts your Serverless Framework v4 HTTP API on your own hostname with provider.domain per stage, documents the DNS and certificate steps and opens a PR.

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

## What the agent does

The agent reads the service as it is deployed today. In a service laid out like the `aws-node-express-api` example in serverless/examples, `serverless.yml` declares `frameworkVersion: "4"`, `provider.runtime: nodejs24.x` on `arm64`, and one function, `api`, with `handler: handler.handler` and a single `httpApi: "*"` event, so API Gateway's HTTP API forwards every path to the function. `handler.js` wraps an Express 5 app with `serverless-http` 4 and answers `/` and `/hello` with JSON and everything else with a 404. The file already carries a commented `# domain: api.example.com` line under `provider` with a link to the Framework's domains guide, and the README's deploy output shows the generated `execute-api` endpoint the service answers on now. There is no `params` block, no CloudFormation `resources` and no test.

The change is the setting the comment points at, read from the Framework's domains guide for v4 rather than from the older `serverless-domain-manager` plugin. The agent sets `provider.domain` to an object: `name: ${param:domain}`, `apiType: http` (the default, and what the `httpApi` event is), and `endpointType: regional`. The hostname comes from a `params` block keyed by stage, `prod` with the real name and `dev` with a stage-prefixed one, so `serverless deploy --stage prod` and the default stage never claim the same name, and the `${param:domain}` reference resolves per stage the way the Framework's own custom-domain example does it. Because the function's event is `httpApi: "*"` with no `basePath`, the path reaches Express unchanged; the agent leaves `basePath` out and says in the README what would change if one were added, since the Framework strips it before the function sees the path.

What the Framework does with that line is what the reviewer needs to know, so the agent writes it down from the guide: on the first `serverless deploy` with the setting, it requests an ACM certificate for the name and validates it through DNS records in the Route 53 hosted zone, creates the API Gateway custom domain and its mapping to the stage's API, and adds A and AAAA records pointing at it; later deploys reuse the certificate, and `serverless remove` keeps the certificate and its validation record so a redeploy is fast. Two conditions are stated plainly: the account must own the zone in Route 53 for the automatic path, and a domain registered elsewhere needs `certificateArn` for a certificate made by hand, `createRoute53Record: false`, and a CNAME the reader creates. The agent also sets `securityPolicy: TLS_1_2`, which the guide names for API Gateway V2 domains.

The agent cannot deploy from its sandbox: that needs the reader's AWS credentials and a Serverless Framework access key, neither of which belongs in a run. What it can check it does: the YAML parses, the keys match the guide's names, and the `params` block resolves for both stages. The pull request's README section gives the exact `serverless deploy --stage prod` command, the two to five minutes the guide says the domain takes to answer, and the `curl` against the new hostname that confirms it, with the generated endpoint still listed as the fallback.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Put this Serverless Framework v4 HTTP API on a custom domain. Read serverless.yml, handler.js, package.json and the README first, and read the Framework's domains guide for v4 rather than any plugin. Replace the commented domain line with a provider.domain object whose name comes from a params block keyed by stage, with apiType http, endpointType regional and securityPolicy TLS_1_2, leaving basePath out because the function takes every path. Document in the README what the first deploy creates (the ACM certificate and its DNS validation, the API Gateway custom domain and mapping, the Route 53 A and AAAA records), what the account must already have (a Route 53 hosted zone for the name), and the third-party registrar variant with certificateArn and createRoute53Record false. Check the YAML parses and both stages resolve. Do not deploy and do not add AWS credentials. Open a pull request that quotes the resolved configuration for each stage and says that no deploy was made.",
  "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

The pull request changes `serverless.yml` (the `provider.domain` object and the `params` block with a `dev` and a `prod` hostname) and the README (a Custom domain section with the prerequisites, the first-deploy steps, the registrar variant and the removal behaviour). Its description quotes the configuration as it resolves for each stage and states that the run deployed nothing.

A reviewer checks the two hostnames against the zone they own, decides whether `dev` should have a domain at all or keep the generated endpoint, and runs `serverless deploy --stage prod` themselves, then the `curl` from the README once the guide's two to five minutes have passed. If the domain is registered outside Route 53 they fill in `certificateArn` from a certificate they create and add the CNAME the README describes.

The function, its handler and the `httpApi` event are unchanged, so the generated `execute-api` endpoint keeps answering beside the new name.

## Run it on every new service in the repository

A team that keeps one service per directory wants each new one on a hostname under the same zone. An automation on the Project with a `github` trigger on `pull_request.opened` and `pull_request.synchronize` runs read-only with a prompt that checks any new `serverless.yml` has a `provider.domain` with a per-stage `params` block and a `TLS_1_2` policy, and comments on the pull request when one is missing. The trigger adds the event after the prompt and substitutes nothing.

When the comment names a service to fix, a handler on your own server sends this body to `POST /o/{org}/sessions` with the service's directory appended to the prompt and the pull request branch in `resources` as `https://github.com/your-org/your-app/tree/<branch>`, with a `request_id` that is a UUID v5 of the head commit SHA so a redelivered event returns the run already started.

## Why run it on Rush?

The configuration is four lines, and the work is knowing what those lines make AWS do: a certificate request, a DNS validation, a custom domain, a mapping and two records, with different steps when the registrar is not Route 53. The agent reads the Framework's own guide for the version the service pins and writes the sequence into the README beside the setting, so the person who deploys knows what to expect before they run the command.

It also stays inside what a run should touch. No credentials enter the sandbox and no deploy happens; the pull request carries the resolved configuration per stage and a plain statement that the reviewer deploys, which is the division of labour a production domain deserves.

## Frequently asked questions

### Does this use the serverless-domain-manager plugin?

No. Framework v4 handles the domain itself through `provider.domain`, which is what the commented line in `serverless.yml` points at. The plugin predates that and is not needed; the pull request says so for anyone who finds older guides.

### What does the first deploy create?

An ACM certificate for the name validated through DNS, the API Gateway custom domain with a mapping to the stage's API, and Route 53 A and AAAA records pointing at it. The guide says access takes two to five minutes after the deploy finishes, and later deploys reuse the certificate.

### My domain is not in Route 53. Does it still work?

Yes, with three changes the README spells out: create the certificate in ACM yourself and set `certificateArn`, set `createRoute53Record: false`, and point a CNAME at the API Gateway domain name the deploy prints. The Framework still creates the custom domain and the mapping.

### Why no basePath?

The function's event is `httpApi: "*"`, so Express receives every path as sent. A `basePath` such as `v1` is stripped by API Gateway before the request reaches the function, which would change what the Express routes see; the README explains that so it is a deliberate choice if added later.

### What does serverless remove do to the domain?

It removes the custom domain, the mapping and the records it created and keeps the certificate and its validation record, so the next deploy does not wait on validation again. The README notes that the certificate stays in ACM until someone deletes it.

## More Serverless Framework jobs

- [Add a Dead-Letter Queue to a Serverless SQS Worker](https://getrush.ai/run/add-dlq/serverless/)
- [Turn On DynamoDB Point-in-Time Recovery in a Serverless Framework Service](https://getrush.ai/run/add-dynamodb-point-in-time-recovery/serverless/)
- [Add a DynamoDB TTL to a Serverless Framework Service](https://getrush.ai/run/add-dynamodb-ttl/serverless/)

## More jobs like this: Hand off a long task

- [Add a Custom Sidebar View to an Obsidian Plugin](https://getrush.ai/run/add-custom-view/obsidian-plugin/)
- [Add a Custom Workflow Builder Step to a Slack Bolt App](https://getrush.ai/run/add-custom-workflow-step/slack-bolt/)
- [Add DAG and Task Documentation to Airflow DAGs](https://getrush.ai/run/add-dag-docs/airflow/)

## 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/)
