Skip to main content
Preview environments in your project can’t use the custom domain set up on your production environment.
By default and for each preview environment, Upsun automatically replaces the custom production domain with an automatically generated URL. If you don’t want to use these default URLs, you can add a custom domain to each of your preview environments (staging or development environment types). To do so, no need to modify your routes configuration. When you add a new custom domain for a preview environment, just attach it to the custom production domain it replaces. If you have multiple custom production domains, you need to select which one you’re replacing.

Example

You have two environments, a production environment and a staging environment. You’ve added the example.com custom domain to your production environment.You want to add the staging.example.com custom domain to your staging environment. To do so, you need to attach the new staging.example.com custom domain to its corresponding custom production domain example.com.You can then access your staging environment through staging.example.com, and still access your production environment through example.com.
If you have multiple custom domains on your production environment, when you set up a custom domain on a preview environment, you don’t need to update your routes configuration either. Upsun automatically figures out the routing of your preview environment based on the following elements:
  • The custom production domains in your existing routes configuration
  • The custom domains for preview environments attached to each of those custom production domains

​
Before you start

You need:
  • A production environment with at least one custom domain already set up
  • At least one preview (staging or development) environment
  • Optional: The Upsun CLI (v4.8.0+)
To prevent abuse, by default you can add custom domains to up to 5 preview environments per project only. This limit doesn’t include the production environment, and you can increase it without charge. To do so, contact Support.
If you delete a custom production domain, all of the attached custom domains for preview environments are deleted too. You need to rebuild the affected preview environments for the deletion to be complete.

​
Add a custom domain to a preview environment

To add a custom domain to a preview environment, follow these steps:
  1. To get the target for your preview environment, run the following command: 
    upsun environment:info edge_hostname --environment <VariableBlock name="ENVIRONMENT_NAME" />
  2. Configure your DNS provider. In particular, make sure your DNS record points to the target of your preview environment.
    Using the target of your production environment to configure your DNS provider is technically possible, but Upsun recommends using the target of your preview environment as a best practice.
  3. Run a command similar to the following: 
    upsun domain:add staging.example.com --environment <VariableBlock name="STAGING_ENVIRONMENT_ID" /> --attach <VariableBlock name="PRODUCTION_CUSTOM_DOMAIN_TO_ATTACH" />
You can’t update a custom domain when it’s used on a preview environment. You can only delete it and create a new one as a replacement.

​
Example

You’ve added the mysite.com custom domain to your production environment. You now want to add the mydev.com custom domain to a preview environment called Dev. To do so, follow these steps:
Run the following command:
upsun domain:add mydev.com --environment Dev --attach mysite.com
In the above example, the Dev environment needs to exist for you to add the mydev.com custom domain successfully. If the Dev environment is later removed, the mydev.com custom domain is removed too.

​
List the custom domains of a preview environment

Run a command similar to the following:
upsun domain:list --environment <VariableBlock name="STAGING_ENVIRONMENT_ID" />

​
Get a specific custom domain used on a preview environment

Run a command similar to the following:
upsun domain:get staging.example.com --environment <VariableBlock name="STAGING_ENVIRONMENT_ID" />

​
Remove a custom domain from a preview environment

Run a command similar to the following:
upsun domain:delete staging.example.com --environment <VariableBlock name="STAGING_ENVIRONMENT_ID" />
Last modified on March 11, 2026