Custom Domain
By default, the platform serves on https://<deployment-prefix>.evaluation.esp-private-agents.com (e.g., https://bxmqxnlxtx.evaluation.esp-private-agents.com). You can put it on your own domain — agent.yourcompany.com and api.agent.yourcompany.com, for example.
What you'll need
| Resource | Why |
|---|---|
| Two subdomains (dashboard + API) | Dashboard and gateway are separate hosts |
| ACM certificate for the dashboard subdomain | Must be issued in us-east-1 (CloudFront requirement) |
| ACM certificate for the API subdomain | Issued in the deployment's region |
| Ability to add CNAME / ALIAS records on your DNS | To point the new domains at the platform |
You can use one cert that covers both subdomains as a SAN, or two separate certs — either is fine.
Steps
1. Issue the ACM certificates
In AWS Certificate Manager:
- For the dashboard subdomain → request a public cert in
us-east-1. CloudFront only accepts certs from this region. - For the API subdomain → request a public cert in the same region as your deployment.
Validate via DNS — ACM gives you CNAME records to add to your DNS. Once validated, copy each certificate's ARN.
2. Set the values on the Management Dashboard
Open Deployment Management Dashboard → Configuration → Custom Domain:
| Field | Example value |
|---|---|
| Dashboard Domain | agent.yourcompany.com |
| API Domain | api.agent.yourcompany.com |
| Gateway Certificate ARN | arn:aws:acm:<deployment-region>:123…:certificate/… (the API cert — issued in your deployment's region) |
| Dashboard Certificate ARN | arn:aws:acm:us-east-1:123…:certificate/… (the dashboard cert, must be in us-east-1 for CloudFront) |
Click Save Configuration.
The platform applies the changes — typically a few minutes for the dashboard (CloudFront update) and the API (ALB).
3. Point your DNS
Add records on your DNS provider:
- Dashboard → CNAME or ALIAS → the CloudFront distribution domain (the platform exposes this in stack outputs after deployment).
- API → CNAME or ALIAS → the ALB DNS name.
After DNS propagation (usually a few minutes, sometimes longer), the platform is live on your domain.
4. Update Cognito callback URLs
If you've changed the host, the Cognito callback / sign-out URLs you set during Authentication need to use the new domain. Update them in the Cognito console.
Additional CORS origins
By default the gateway only accepts browser requests from the dashboard itself. The browser blocks requests from any other origin. If you want a different site to talk to the platform — the typical case is embedding the chat agent as a widget on your company's marketing page or product site — that site's origin needs to be on the allow-list.
Under Custom Domain → Additional CORS Origins, you can add as many extra origins as you need. The dashboard origin is always allowed and is shown as a locked entry; you can only add to the list, not replace the default.
Adding an origin
Click Add, paste the full origin, and save. An origin is the scheme://host[:port] part of a URL — no path, no trailing slash. Examples:
| ✅ Valid | ❌ Not valid |
|---|---|
https://www.yourcompany.com | www.yourcompany.com (missing scheme) |
https://app.yourcompany.com:8443 | https://www.yourcompany.com/ (trailing slash) |
http://localhost:5174 | https://yourcompany.com/embed (has a path) |
Wildcards (*) aren't supported — the platform uses CORS with credentials, which requires exact-string origin matches. If you serve from multiple hosts, add each one.
Applying the change
The list is stored on the deployment record when you click Save Configuration, but it takes effect on the next deploy. After saving, go to the Updates tab and re-deploy the current version (or a new one — either works). One deploy applies the new list to both the gateway and the media bucket, so multimodal uploads from the new origin work too.
If you've embedded the agent and the browser console still shows a CORS error after a deploy, double-check that the Origin header the browser sends matches the entry byte-for-byte — a trailing slash or different port is enough to break the match.
Order matters
If you're switching from the default to a custom domain:
- Issue and validate the certs first. Otherwise the platform can't terminate TLS.
- Update the platform config before pointing DNS — saves users from hitting a broken cert.
- Update Cognito callback URLs as part of the same maintenance window — sign-in breaks otherwise.
Tips
- Use a wildcard cert (
*.yourcompany.com) if you have one — covers both subdomains and any future ones. - Keep the cert in us-east-1 for the dashboard, even if your deployment is in another region. CloudFront is global; it lives in
us-east-1. - Set a short DNS TTL beforehand. If you're moving from one host to another, drop TTL to 60 seconds a few hours before the change so rollbacks are quick.
Common gotchas
| Symptom | Likely cause |
|---|---|
| Cert can't be selected for the dashboard | Cert isn't in us-east-1. Re-issue there. |
| TLS handshake fails on API | API cert ARN is wrong region or wrong domain. Recheck. |
| Browser shows wrong cert | DNS still resolves to the old host; clear your DNS cache or wait for propagation. |
| Sign-in works on custom domain but redirect goes to default | Cognito callback URLs not updated to the new domain. |