Adding Domains

Introduction

A domain is a front door: the hostname your visitors type, such as shop.example.com. When you add a domain to NiceTryBot, you also tell it where your application actually lives, which we call the origin. Once the domain's DNS points at the edge, every visitor passes through NiceTryBot on the way to your origin.

Adding a domain never interrupts your visitors. Nothing changes until you verify the domain and point its DNS records at the edge, and even then every domain starts in observe mode, where NiceTryBot watches and tags traffic but lets everyone through.

Adding a Domain

To add a domain, open the cog menu in the top right of the control panel and choose Domains & origins. Then click Add domain.

Adding a Domain Using AI

The Add domain modal includes an Add with AI button, which copies a prompt for Claude Code, Cursor, or another coding agent. Paste it into an agent that is working in your application's repository and it will:

Ask you to connect it to NiceTryBot's MCP server with an API token, which an administrator creates in Admin → API tokens.
Work out your public hostname, an origin hostname, and the endpoints machines call, and check them with you.
Serve your application at the origin hostname.
Add the domain to NiceTryBot and verify it.
Make your origin refuse requests that skip the edge.
Test everything, then stop so you can try it before any DNS changes.
Point DNS at the edge only when you say so.

If you would rather point an agent at this page directly, you may use a prompt like the following:

Read https://docs.nicetrybot.com/docs/0.x/domains.md and https://docs.nicetrybot.com/docs/0.x/origins.md, then help me put my app behind NiceTryBot. Check every hostname and DNS record with me before you change it.

Adding a Domain From the Command Line

You may also add a domain using the nicetrybot command, on your server or from your laptop:

Terminal

nicetrybot domains add claims.example.com claims-origin.example.com

The command accepts the same settings as the modal, such as --www and --host-header=rewrite, and prints the records and origin secret you need for the steps below.

Domain Fields

The Add domain modal asks for the following:

Field	Description
Domain	The hostname visitors type, without `https://` or a path. For example, `claims.example.com`. Each domain may only be added once per installation.
Serve www. too	When checked, visitors to `www.` in front of your domain get the same site, counted under the same domain. Turn it off for a subdomain nobody types `www.` in front of.
Origin URL	Where the edge forwards human traffic, such as `https://app.example.net`. It must use `http` or `https` and must be a different host than the domain, or requests would loop back to the edge.
Host header	Which `Host` header your origin receives. See Host Headers below.

Once you click Add domain, NiceTryBot creates the domain, generates its verification token and origin secret, and takes you to the domain's page to finish setup.

Host Headers

By default, NiceTryBot will pass the visitor's host through, so your origin receives the same Host header the visitor sent. This is what most applications expect.

Some platforms route requests by Host header, such as Laravel Vapor, Vercel, Netlify, Heroku, Render, and CloudFront. For these, choose Rewrite to the origin's host instead. Hosting Platforms has the exact command for each. Your origin will receive the origin URL's host, or the value you enter under Host header sent to the origin. When rewriting, your application should build links from its configured URL rather than the incoming Host header.

If a shared origin needs to know which site a visitor asked for, enter one or more header names under Forward the visitor's host in a header, such as User-Custom-Domain. The edge always sends X-Forwarded-Host as well.

Hosting Platforms

The right settings depend on where your origin is hosted. Find your platform below, copy its command, and swap in your own hostnames. Each command prints the steps to go live, including the origin secret.

Tip

Not sure which platform you're on? Your agent can tell from your repository. Files like vapor.yml, vercel.json, netlify.toml, Procfile, and render.yaml give it away. Ask it to read this section and give you the command for your app.

Your Own Server

If your application runs on a server you manage, such as one provisioned by Laravel Forge or Ploi, or any server running Nginx, Caddy, or Apache, the defaults are all you need. Point a second hostname, such as shop-origin.example.com, at your server and add it to your site's domains (an alias in Forge) so it gets a TLS certificate. Then add the domain:

Terminal

nicetrybot domains add shop.example.com shop-origin.example.com

Your application keeps receiving the visitor's own Host header, so nothing else about it needs to change.

Laravel Vapor

Vapor serves your application through CloudFront, which only answers hostnames it knows. Give your environment an origin hostname, as you would any Vapor custom domain, and deploy:

vapor.yml

environments:
    production:
        domain:
            - docs-edge.example.com

Then add the domain, rewriting the Host header to the origin's own:

Terminal

nicetrybot domains add docs.example.com docs-edge.example.com \
  --host-header=rewrite \
  --forwarded-host-header=X-Forwarded-Host

Your application now receives docs-edge.example.com as its host, so set APP_URL to your public URL and Laravel will build links that point back through the edge:

.env

APP_URL=https://docs.example.com

AWS CloudFront

If your origin sits behind a CloudFront distribution you manage, such as one in front of a load balancer or an EC2 instance, use the distribution's domain name as the origin:

Terminal

nicetrybot domains add shop.example.com d111111abcdef8.cloudfront.net \
  --host-header=rewrite \
  --forwarded-host-header=X-Forwarded-Host

CloudFront only passes along the request headers its origin request policy allows, so by default your application would never see the origin secret. In the distribution's behavior, set the origin request policy to the managed AllViewerExceptHostHeader policy, which forwards every header the edge sends, including X-NiceTry-Origin-Secret and X-Forwarded-Host.

Warning

CloudFront answers cached responses without asking your origin, and anyone can request your distribution's domain directly. Use the managed CachingDisabled cache policy for your pages so every request reaches your origin lock. Caching static assets is fine.

Vercel

Vercel replaces X-Forwarded-Host with its own hostname before your application sees it, so name a header of your own to carry the visitor's host:

Terminal

nicetrybot domains add shop.example.com my-app.vercel.app \
  --host-header=rewrite \
  --forwarded-host-header=X-Visitor-Host

Use your project's production hostname as the origin, not a preview deployment URL. Then configure your application's public URL, such as https://shop.example.com, so the links it builds point back through the edge.

Laravel Cloud, Netlify, Heroku, and Render

These platforms route by Host header too. Use the hostname your platform gave your application as the origin:

Platform	Origin
Laravel Cloud	`my-app-main-a1b2c3.laravel.cloud`
Netlify	`my-site.netlify.app`
Heroku	`my-app-1a2b3c4d5e6f.herokuapp.com`
Render	`my-app.onrender.com`

Then add the domain. A header name of your own, such as X-Visitor-Host, reaches your application untouched on every platform:

Terminal

nicetrybot domains add shop.example.com my-site.netlify.app \
  --host-header=rewrite \
  --forwarded-host-header=X-Visitor-Host

As with Vercel, configure your application's public URL so its links point back through the edge. For a Laravel application, that is APP_URL.

Reading the Visitor's Host

An application that serves a single site only needs its public URL configured. If one application serves several sites, read the visitor's host from the header you chose:

PHP

$site = $request->header('X-Visitor-Host', $request->getHost());

Anyone can send that header to an unlocked origin, so only trust it once your origin refuses requests that skip the edge.

Going Live

Each domain's page includes a Go live panel with the steps needed to route the domain through NiceTryBot. The steps are designed to be completed in order.

Verifying Ownership

First, prove the domain is yours by adding a TXT record at your DNS provider. The record's name and value are shown on the domain's page, and look like this:

Type	Name	Value
`TXT`	`_nicetrybot.shop.example.com`	`nicetrybot-verify=3f9a…`

Once the record exists, click Check TXT record. NiceTryBot looks up the record using public DNS and marks the domain as Live when the value matches. A brand new record can take a few minutes to appear, so if the check doesn't find it right away, wait a moment and try again.

After the domain is verified, you may remove the TXT record whenever you like.

Note

The verification check runs on your queue. If the check never finishes, make sure the worker service is running using nicetrybot status.

Trying the Preview Link

If your installation has a preview zone configured using the NICETRY_PREVIEW_ZONE environment variable, each domain gets a preview hostname. For example, shop.example.com becomes shop-example-com.preview.example.com. The preview link serves your site through the edge before you change any DNS, and your origin is asked for the real hostname, so it serves exactly what your visitors will get.

Preview hostnames are disabled when NICETRY_PREVIEW_ZONE is empty, which is the default.

Pointing DNS at the Edge

Next, point the domain at your NiceTryBot server. Subdomains use a CNAME record pointing at your edge's hostname, which is the value of NICETRY_EDGE_HOSTNAME:

Type	Name	Value
`CNAME`	`shop.example.com`	`panel.example.com`
`CNAME`	`www.shop.example.com`	`panel.example.com`

Apex domains, such as example.com, can't use a CNAME record. Instead, add an A record for each of your edge's addresses, which are the values of NICETRY_EDGE_ADDRESSES:

Type	Name	Value
`A`	`example.com`	`203.0.113.10`

The domain's page shows the exact records for your installation. Then, click Check DNS to confirm the records are in place.

Warning

Delete any other A, AAAA, or ALIAS records for the name first. The edge only listens on IPv4, so a leftover AAAA record would let IPv6 visitors skip NiceTryBot entirely. The Check DNS button only passes once every address points at the edge and no AAAA records remain.

If you would like to be able to roll back quickly, lower the TTL on your existing records a few hours before you switch them. Once DNS points at the edge, TLS certificates are issued automatically the first time a visitor arrives.

Finally, the last step of the Go live panel is to lock your origin so that only the edge may reach it. This step is important enough to have its own page: Protecting Your Origins.

Protection Modes

Every domain has a protection mode, which decides what NiceTryBot does with the traffic it tags. You may change a domain's mode at any time from the Protection mode panel on its page:

Mode	Description
Off	Proxy and log only. No tagging.
Observe	Tag suspicious traffic, but let it through. This is the default for new domains.
Enforce	Send tagged traffic to the gym or block it.

We recommend leaving a new domain in Observe mode for a few days. You can watch what NiceTryBot would have done in Activity, tune your rules, and switch to Enforce once you are comfortable. The bot gym and tarpits only hold visitors on domains in Enforce mode.

Note

If the edge can't reach the control panel, it fails open and sends everyone to your origin. An outage of the panel will never take your sites down with it.

Origin Settings

The Origin panel on a domain's page controls how the edge talks to your application:

Setting	Description
Origin URL	Where human traffic is forwarded.
Timeout (seconds)	How long the edge waits for your origin, from 5 to 120 seconds. Defaults to 30.
Host header	Pass the visitor's host through, or rewrite it. See Host Headers.
Server header visitors see	The `Server` header the edge sends. Defaults to `nginx`. Pretending to be something old and unpatched can make a honeypot more tempting.
HSTS	Off, on for a year, or on with subdomains and preload. Preloading is hard to undo, so enable it with care.
Let browsers cache /img, /css and /js	Caches images for a day and CSS and JavaScript for a week.
Serve www. too	Whether `www.` in front of the domain serves the same site.

The edge picks up new domains and changed settings within about 30 seconds. There is no need to restart anything.

Pausing and Removing Domains

Once a domain is verified, you may Pause protection from its page. A paused domain still routes through the edge, but protection stops and traffic flows straight to your origin. Click Resume to turn protection back on.

To remove a domain entirely, click Remove domain, or run nicetrybot domains remove with its hostname. Removing a domain stops protection and deletes its request history, which can't be undone.

Warning

Point the domain's DNS back at your origin before removing it. Otherwise, visitors will still arrive at the edge, which no longer knows where to send them.

Domain Limits

Each NiceTryBot installation protects up to 10 domains for free. Every domain on the Domains & origins page counts toward the limit, including domains that are still awaiting verification. To protect more, an administrator may add a More domains licence key in Admin → Add-ons. Each pack adds 100 domains, and packs stack. You can learn more about licence keys in the add-ons documentation.