# Domains

> Connect and manage domains for your Tarout applications

# Domains

Every application gets a free `*.tarout.app` address on every plan. You can also
buy a supported domain through Tarout or connect a domain you already own.

Connecting your own domain to an application needs a paid plan (Starter or
above). Buying a domain does not, but a domain bought on the free plan cannot be
connected to an app until you upgrade.

## Connect a domain you already own

1. Open **Dashboard → Domains** and choose **Add External Domain**.
2. Enter the exact hostname you want to serve, such as `example.com` or
   `app.example.com`.
3. Add the records shown by Tarout at your current DNS provider. Tarout chooses
   the routing record for you (see below). If Tarout also shows an ownership TXT
   record, add it exactly as shown.
4. Wait for both domain verification and the managed SSL certificate to become
   active.
5. Assign the verified domain to an application from the domain detail page or
   the application's **Domains** tab.

Always copy the live values from the dashboard (or `tarout domains instructions
<domain>`). Targets and verification tokens are specific to your domain and can
change; the examples below are illustrative.

### Subdomain

For a hostname such as `app.example.com`, Tarout shows a CNAME:

```text
Type: CNAME
Name: app
Value: <target shown in the dashboard>
```

### Root (apex) domain

A root domain such as `example.com` connects in one of two ways, depending on
where its DNS is hosted. Tarout detects this when you add the domain.

- **DNS hosted on Cloudflare** - Tarout shows a CNAME record for the root. Set it
  to **Proxied** (orange cloud). A DNS-only root record will not route.
- **Any other DNS provider** - Tarout shows an A record for the root that points
  at Tarout's apex gateway. Replace any existing A record on the root with it.

For a root domain on the apex gateway, visitors to `example.com` are redirected
to `www.example.com` by default, so connect `www.example.com` as well. To serve
the app on the bare domain instead, open the domain's detail page and change
**Root domain behavior**. The DNS records stay the same in both modes.

### Ownership TXT record

In most cases the routing record is all you add: pointing your DNS at Tarout
proves that you control the domain. Tarout asks for an extra ownership TXT
record, named `_tarout-verification.<your hostname>`, only in specific cases,
for example when the hostname already points at Tarout before you add it (such
as a record left over from a deleted app) or when its record is proxied through
Cloudflare. Add it only when the dashboard shows it.

## Buy a domain through Tarout

Open **Dashboard → Domains → Search & Buy**, search for an available supported
domain, enter the registrant details, and complete checkout. Registration begins
only after payment is confirmed. Availability and price are checked again before
registration, so a domain can become unavailable between search and checkout.

Purchased domains use managed DNS. Transfers and registrar operations that are
not exposed by the managed registrar are handled through a support request.

### Renewal

Renewal is not automatic today. A purchased domain is renewed only after its
renewal is paid, and the dashboard does not offer a renewal payment yet. To
renew, run `tarout domains renew <domain>` (add `--years <n>` for more than one
year) and complete the payment. Tarout emails the organization owner 30, 14, 7,
3, and 1 days before a domain expires.

The **Auto Renew** switch on the domain detail page can only be turned on after
this cycle's renewal has been paid, and it is not available for `.sa` domains,
which must be renewed manually before they expire.

## SSL certificates

Tarout provisions and renews certificates automatically after DNS and ownership
checks succeed. Standard non-wildcard external domains use HTTP validation, so
they do not require an `_acme-challenge` TXT record. A domain is ready for HTTPS
only when both its hostname and certificate statuses are active.

If certificate issuance is blocked by a CAA policy, the dashboard shows the CAA
record that must be added at your DNS provider.

## Wildcard domains

Wildcard domain attachment is not currently available. Add each exact apex or
subdomain hostname you need, such as `example.com` and `www.example.com`, as a
separate domain. This prevents a wildcard from being accepted before both the
provider entitlement and application-origin routing are supported end to end.

## Troubleshooting

| Issue | What to check |
|---|---|
| Domain remains pending | Confirm the displayed A or CNAME record (and the ownership TXT record, if one was shown) is present exactly as shown, and wait for propagation. A root domain on Cloudflare DNS must be set to Proxied. |
| Certificate remains pending | Confirm the A or CNAME record points to Tarout and check the dashboard for a CAA warning. Standard non-wildcard domains do not need an ACME TXT record. |
| Domain verifies but does not serve the app | Confirm the domain is assigned to the intended application and that the application is deployed. For a root domain on the apex gateway, remember it redirects to `www` unless you switch **Root domain behavior** to serve the app directly. |
| Wrong DNS instructions | Make sure you entered the exact hostname. Tarout uses a CNAME for a subdomain, and for a root domain either a proxied CNAME (DNS on Cloudflare) or an A record (any other DNS provider). |
| Purchased domain registration is pending | Keep the checkout reference and check the domain detail page; contact support if the status reports action required or failed. |

---

## Every Tarout agent guide

- [Start Here (Agents)](https://tarout.sa/docs/for-ai/start.md)
- [Overview](https://tarout.sa/docs/for-ai.md)
- [Deploying an app](https://tarout.sa/docs/for-ai/deploy.md)
- [Databases](https://tarout.sa/docs/for-ai/database.md)
- [Object storage](https://tarout.sa/docs/for-ai/storage.md)
- [Custom domains](https://tarout.sa/docs/for-ai/domains.md)
- [Plans and upgrades](https://tarout.sa/docs/for-ai/billing.md)
- [Troubleshooting](https://tarout.sa/docs/for-ai/troubleshoot.md)
- [Agent Onboarding](https://tarout.sa/docs/for-ai/onboarding.md)
- [CLI Reference](https://tarout.sa/docs/for-ai/cli-reference.md)
- [CLI JSON Schema](https://tarout.sa/docs/for-ai/cli-json-schema.md)

Whole corpus in one file: https://tarout.sa/llms-full.txt · index: https://tarout.sa/llms.txt
Any docs page is raw markdown at the same URL + `.md`. Short link to the entry point: https://tarout.sa/deploy.md