> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reliantlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Add a custom domain with automatic HTTPS

> Serve a hosted environment on a hostname you own: claim it, publish the CNAME and TXT records forge prints, bind a workload, and get HTTPS issued for you.

By the end of this guide, a hosted environment answers on a hostname you own, over HTTPS, with a certificate the platform obtains and renews. You publish two DNS records once; everything after that is a command.

A domain belongs to your organization and a binding points it at one environment's workload or site, so you can move a verified domain between environments without touching DNS. [Custom domains](https://docs.reliantlabs.io/hosting/custom-domains.md) explains the model, the record shapes and each state.

## Before you begin

* A Forge project with a workload or static site deployed to a hosted environment, here `prod` serving a workload named `api`. [Deploy a Go API with managed Postgres](https://docs.reliantlabs.io/guides/hosting/deploy-go-api-managed-postgres.md) gets you there.
* Access to the DNS settings of the hostname you are adding.
* Forge v1.6.1 or later (`reliant forge --version` inside the project). Signed in to Reliant, `forge cloud domain` needs no separate login.

**1. Claim the hostname**

`--env` names the environment whose control plane to talk to; the domain itself is not tied to it:

```bash terminal theme={null}
reliant forge cloud domain add app.example.com --env prod
```

```text Output (from a run with guides-sandbox.example.com) theme={null}
Added guides-sandbox.example.com (pending_dns)

Set these DNS records at your registrar:

  TYPE    NAME                                            VALUE                                                                     STATUS
  CNAME   guides-sandbox.example.com                      ingress.reliantlabs.dev                                                   not checked yet
  TXT     _reliant-challenge.guides-sandbox.example.com   reliant-domain-verification=cMxNP6R7-y6KE-J-JJ_VWaR2ZqjMRs3srY0faV3rdJo   not checked yet
```

A subdomain gets a `CNAME`; an apex gets an `A` record instead. Claiming does not reserve the name: the first organization to verify it takes it.

**2. Bind it to a workload**

A claimed domain serves nothing until it is bound. `--target` is a workload or frontend name in that environment:

```bash terminal theme={null}
reliant forge cloud domain bind app.example.com --env prod --target api
```

```text Output theme={null}
Bound guides-sandbox.example.com → api, in prod.
It is pending_dns and will start serving once it verifies.
```

For `www`, add it as a second domain and bind it with `--redirect-to app.example.com` instead of `--target`.

**3. Publish the DNS records**

At your DNS provider, create both records exactly as `domain add` printed them, the long TXT token included. `domain show` prints them again at any time:

```bash terminal theme={null}
reliant forge cloud domain show app.example.com --env prod
```

```text Output (trimmed) theme={null}
guides-sandbox.example.com
  state:   pending_dns
  source:  external
  serving: api in c21469f8-d9af-4985-9eeb-7767168ab48d
  hsts:    host only
```

Leave both records in place for good: the TXT token is re-checked on every pass. Do not publish an `AAAA` record.

**4. Verify and wait for HTTPS**

The platform re-checks on its own. `domain verify` checks now and prints what is still missing. This guide's run used a reserved `example.com` name with no DNS, so its check failed:

```bash terminal theme={null}
reliant forge cloud domain verify app.example.com --env prod
```

```text Output (trimmed) theme={null}
  state:   pending_dns
  error:   customdomain: domain does not resolve to the platform: guides-sandbox.example.com does not resolve

  CNAME   guides-sandbox.example.com   ingress.reliantlabs.dev   NOT YET — guides-sandbox.example.com does not resolve yet
```

Once both records resolve, the state moves through ownership checking and certificate issuance to `live`, usually within minutes of DNS propagating. `reliant forge cloud domain ls --env prod` shows the state of every domain in the organization. Then `curl -I https://app.example.com` should answer from your workload. `domain verify` exits 0 even when the check fails, so read the `state:` line rather than the exit code.

**5. Remove a domain you no longer need**

`unbind` stops serving and keeps the verification; `rm` releases the hostname entirely:

```bash terminal theme={null}
reliant forge cloud domain unbind app.example.com --env prod
reliant forge cloud domain rm app.example.com --env prod
```

```text Output theme={null}
Unbound guides-sandbox.example.com. The domain and its verification are kept; re-bind it any time.
Removed guides-sandbox.example.com. The hostname is free for another organization to claim.
```

Deleting an environment releases its bindings and keeps the domains.

## What this does not do

* Domains are not declared in KCL, and a deploy never creates one. A hosted spec that carries a `domains` field is refused at render.
* It does not change your DNS. Reliant cannot speed up your provider's propagation.
* There is no `AAAA` record and no IPv6 serving today.

## Troubleshooting

> [accordion] customdomain: domain does not resolve to the platform
>
> The `CNAME` (or the apex `A` record) is missing, misspelled or not propagated yet. Compare what your provider shows with `domain show` character for character, then run `domain verify` again.

> [accordion] Waiting for DNS for more than an hour
>
> Some providers append your domain to a record name, producing `_reliant-challenge.app.example.com.example.com`. Check the saved name. Fix the record and run `domain verify`; do not remove and re-add the domain, which can run into certificate rate limits.

## Next steps

> [card] [Manage production secrets](https://docs.reliantlabs.io/guides/hosting/manage-production-secrets.md)
>
> Give the same environment its own secret values, set from stdin.

> [card] [Custom domains](https://docs.reliantlabs.io/hosting/custom-domains.md)
>
> Record shapes, every state, conflicts and certificates.

> [card] [Secrets](https://docs.reliantlabs.io/hosting/secrets.md)
>
> The hosted secret store each environment has.

> [card] [Security model](https://docs.reliantlabs.io/deep-dives/security-model.md)
>
> How Reliant scopes credentials and keeps secrets write-only.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.