All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

More jobs like this: Hand off a long task

Keep reading