Configure Custom Domains

Environment domains give your environment a memorable, stable URL that persists across deployments. Instead of using a deployment-specific URL that changes with each deploy, an environment domain always points to the environment's current deployment.

Phemeral supports two kinds of environment domains:

1. Custom domains — hostnames you own, such as api.example.com.
2. Phemeral subdomains — vanity subdomains of .phemeral.app, such as my-api.phemeral.app.

Both are assigned to an environment, not a specific deployment. Traffic is routed to whichever deployment is currently active on that environment, and when a new deployment is set as current, the domain automatically begins routing to it.

Custom Domains

Use a custom domain when you want your environment to be reachable via a hostname you already own (for example, api.example.com or app.example.com).

How custom domains work

• You can add any fully-qualified hostname you control, as long as it is not already in use by another Phemeral environment.
• The domain is created in a Pending DNS state. Phemeral checks whether the hostname's DNS records point at the platform.
• Once the DNS records are detected, the domain becomes Active and traffic is routed to the environment's current deployment.
• If the DNS check fails, the domain remains in a pending state

DNS requirements

Before adding a custom domain, configure your DNS provider to point the hostname at Phemeral using one or both of the following record types:

The exact IP addresses are shown in the dashboard when you add a custom domain.

Add a custom domain

1. Navigate to your project in the dashboard.
2. Open the environment you want to assign the domain to.
3. In the Domains section, click Add Domain.
4. Enter the full hostname (for example, api.example.com).

If its DNS records are already pointing at Phemeral, it becomes Active right away. Otherwise it enters the Pending DNS state.

Verify a custom domain

If a custom domain is pending, you can trigger a DNS recheck at any time:

1. In the Domains section, find the pending custom domain.
2. Click Verify DNS.

If the DNS records are correct, the domain becomes Active. If not, fix the configuration and try again.

Remove a custom domain

1. Open the environment in the dashboard.
2. In the Domains section, find the custom domain you want to remove.
3. Click Remove Domain.

Traffic to the removed domain will no longer be routed to your environment.

Phemeral Subdomains

Use a Phemeral subdomain when you want a clean, memorable URL under .phemeral.app without managing external DNS.

How Phemeral subdomains work

• Every environment automatically receives a default subdomain in the format {project-name}-{environment-name}.phemeral.app when it is created.
• You can add additional vanity subdomains (for example, api.phemeral.app or my-app.phemeral.app) as long as they are not already taken.
• Phemeral subdomains are Active immediately — no DNS setup is required.

Add a Phemeral subdomain

1. Navigate to your project in the dashboard.
2. Open the environment you want to assign a subdomain to.
3. In the Domains section, click Add Domain.
4. Enter the subdomain you want, including the .phemeral.app suffix (for example, my-app.phemeral.app).

If the subdomain is available, it is assigned to your environment immediately. Otherwise, choose a different subdomain and try again.

Remove a Phemeral subdomain

1. Open the environment in the dashboard.
2. In the Domains section, find the subdomain you want to remove.
3. Click Remove Domain.

Traffic to the removed subdomain will no longer be routed to your environment.

Multiple Domains

An environment can have any mix of custom domains and Phemeral subdomains. All of them route to the same current deployment.

Deployment Domains vs. Environment Domains

Deployment domains are auto-generated and immutable. They are useful for previewing or testing a specific deployment. Environment domains follow the current deployment as it changes.