---
title: "Custom domain and HTTPS: the while.sh docs"
url: https://while.sh/en/docs/building-blocks/custom-domains/
updated: 2026-11-09
---

# Custom domain

Your app answers at your address, like planning.acme.com, with its HTTPS certificate. Your agent declares the domain, and you add the DNS records it gives you.

> You, to your agent: Put the app on planning.acme.com.

## What your agent writes

Your agent writes it in while.yaml, at the root of your app:

```yaml titre="while.yaml"
services:
  - name: web
    port: 3000
    domains: [app.example.com]
```

## When to use it

Use it when the app must live at your address.

## How it works

Your app answers at your address, like `app.example.com`, with its HTTPS certificate. while verifies the domain with a DNS record, then serves it and routes it to the right version.

## What to know

A subdomain points to `edge.while.cloud` with a CNAME. A bare domain (example.com) takes an ALIAS, an ANAME or a flattened CNAME to that same name, if its DNS provider supports it (Cloudflare, Bunny, OVH…). As a last resort only, it takes the A and AAAA addresses of while's entry point instead, given with the proof (TXT): they can change, a change is announced at `https://app.while.sh/v1/network`, and while then warns the domains that point to them. The domain is checked every five minutes, and served as soon as it is proven, at the latest at the next release. The domain's certificate is issued on its first visit.

## Your agent's MCP tools

Your agent handles it with the `get_app_status` tool.

## Guides

- [Put your app on your own domain name, over HTTPS, from your AI agent](/en/guides/custom-domain/)