# Domains

URL: /products/site/domains/site-domains · Id: `page:products/site/domains/site-domains`

> Every Domain a Startup uses is a record with a role, a state and an owner of record, so Agents find, buy, connect, renew and move names as data.

A [Domain](/business/nouns/domain) is a hostname a [Startup](/business/nouns/startup) answers on, kept as a record with a role, a state and an owner of record. An [Agent](/business/nouns/agent) finds, buys, connects, renews and moves Domains as data.

## Three ways to get a Domain
A Startup gets each Domain one of three ways, and the record keeps which in `acquired`:

- **Claimed.** A free one-label name under a platform Domain, ready in seconds. Every new Startup starts here, through [claim](/business/nouns/domain/claim).
- **Registered.** A name bought for the Startup with [register](/business/nouns/domain/register).
- **Connected.** A name the Startup already holds, attached with [connect](/business/nouns/domain/connect) and verified through DNS.

A claimed name is its own site in every browser, because the public suffix list carries its parent. No cookie or session crosses between sibling Startups. Claim refuses reserved labels such as `www`, `api`, `mcp` and `docs`, and never reissues a released label.

A claimed name carries a Startup through [Idea](/business/nouns/idea) and [Building](/business/lifecycle/states/building). Here an Agent registers `linguaroster.com` for a marketplace of certified translators:

**API**

```bash
curl -X POST https://api.sb/linguaroster.com/domains/register \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"linguaroster.com","startup":"startup_linguaroster"}'
```

**SDK**

```ts
import { $ } from 'startup-builder'

const domain = await $.Domain.register({ hostname: 'linguaroster.com', startup: 'startup_linguaroster' })
```

**CLI**

```bash
npx startup-builder do Domain.register --json '{"hostname":"linguaroster.com","startup":"startup_linguaroster"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Domain.register({ hostname: 'linguaroster.com', startup: 'startup_linguaroster' })"
  }
}
```

## Find and buy a name
To find and buy a name, an Agent runs four steps in order:

1. [Search](/business/nouns/domain/search) the name across extensions. Each candidate returns its availability, first-year price, renewal price and extension rules.
2. [Clear](/business/nouns/brand/clear) the name. One call reads trademark registers, Domain availability and social handles.
3. Compare three-year cost. A premium name that renews at a premium price shows that cost first.
4. Register the winner.

Some extensions sell only multi-year terms or require a local presence. Search drops any candidate whose rules the owner of record fails, so it never reaches the register step.

Buying a Domain spends money and cannot be undone. It runs under the spend [Limits](/business/nouns/limit) of the Startup and waits out the delay window for one-way spending. A purchase over the Limit waits for an [Approval](/business/nouns/approval).

A name someone else holds is bought through escrow, never by direct payment. Its price is a [Decision](/business/nouns/decision), with the rejected candidates attached.

A self-serve Startup holds its chosen name as a `candidate` until a person [claims](/business/nouns/startup/claim) the Startup. The brand card shows the price and buys nothing. At the claim, the name registers to the holder of the Startup's Stripe account, so it belongs to its owner from the first day.

## Roles
Each Domain has one `role` on the [Thing](/business/nouns/thing) it serves:

| `role` | What it does |
| --- | --- |
| `canonical` | The address the Startup answers as. Every link and every `$id` uses it. A [Site](/business/nouns/site) has exactly one. |
| `alias` | Another address the Startup answers on, such as `www`. It renders in place and names the canonical Domain as its canonical link. |
| `redirect` | A name the Startup holds but does not answer on: a misspelling, another extension, the old name after a rebrand. It answers with a permanent redirect to the same path on `to`. |
| `preview` | Serves the `test` environment, or one pending [Change](/business/nouns/change), to its reviewers. |
| `tenant` | Serves one [Tenant](/business/nouns/tenant), such as `acme.linguaroster.com` or a name the [Customer](/business/nouns/customer) owns. |
| `signIn` | A Customer's email domain, whose sign-ins follow the Tenant's policy. |
| `outreach` | Sends cold mail only, apart from the Domain receipts use. |

A rebrand makes the new Domain canonical and turns the old one into a `redirect`. Every old link still lands, and search engines move the old standing to the new name.

A [Setting](/business/nouns/setting) places each Tenant: in the path (`linguaroster.com/acme`), in the path with a sigil (`linguaroster.com/~acme`), or in the host. Each [Product Template](/business/nouns/product-template) sets a default.

## Customer names on a Tenant
A Customer's admin connects a name it owns, such as `portal.acme.com`, to its Tenant in the [Portal](/business/nouns/portal). The admin sees two records to set and the status of each check.

A TXT record proves ownership, and a CNAME points the name at `customers.linguaroster.com`, a name on the Startup's canonical Domain. When the Startup graduates or sells, that name moves with it, and no Customer edits DNS.

Every connect asks for a fresh ownership proof. A name left pointing at the platform after its Tenant ends cannot be taken by another Tenant.

The connect spends nothing of the Startup's, so it runs with no delay window and no Approval. How many names a Tenant connects is an [Entitlement](/business/nouns/entitlement) of its [Offer](/business/nouns/offer), and past the count the connect follows the Entitlement's `atBound`. A Tenant never connects a wildcard name, and cookies on its name reach that name only.

When the Tenant ends, or its Offer no longer includes the feature, the name stops serving. The Customer sees which record to remove, and the Domain record stays.

## The Domain lifecycle
A Domain moves through named states in `state`. Five are observed from the world; the rest follow an [Action](/business/nouns/action).

| State | Meaning |
| --- | --- |
| `candidate` | Under consideration, checked for availability and trademark conflicts |
| `held` | Held for a Startup before it is put to use |
| `claimed`, `registered`, `connected` | Acquired, by one of the three paths |
| `verifying` | DNS, ownership and the certificate are being checked |
| `live` | Serving over HTTPS with a valid certificate |
| `degraded` | Live, with one check failing; the record names the check and its fix |
| `expiring` | Inside its renewal window: 90 days for a canonical Domain, 60 for others |
| `lapsed` | The registration ended unrenewed; an [Incident](/business/nouns/incident) opens the same day |
| `renewed`, `transferred`, `released` | Kept, moved with [transfer](/business/nouns/domain/transfer), or let go with [release](/business/nouns/domain/release) |

[Renew](/business/nouns/domain/renew) runs at the start of the window, so a failed payment leaves months to fix. A canonical Domain renews to stay two years ahead. Other names go through a review that renews or releases each one.

A Domain that ever received mail, hosted a [Mailbox](/business/nouns/mailbox) or verified an outside account never lapses. Its `carriedIdentity` never resets, release refuses it, and a [Dormant](/business/lifecycle/states/dormant) Startup keeps renewing it. Its inbound mail lands in a sink for the Startup's return.

A released Domain keeps its record and history. A released claimed label never goes to another Startup.

## Certificates and wallets
Every serving Domain holds a certificate that renews automatically, and each renewal proves control of the name again. A connected Domain points one CNAME at the platform, so every renewal passes with no step from the founder. An apex whose DNS host refuses a CNAME points at the platform's fixed addresses instead.

A failed renewal moves the Domain to `degraded` weeks before the certificate expires. A degraded canonical Domain opens an Incident. [Pages](/business/nouns/page) keep linking to it until the certificate expires; a link to a Domain that is not serving renders as plain text.

Registering or connecting a Domain also registers it with Stripe as a payment method domain on the Startup's account. One-tap payment buttons then render in every embedded payment form, and `walletsEnabled` records it. Address resolves, a [Live](/business/lifecycle/states/live) entry check, reads both.

## One address for every Interface
The canonical Domain is the address of the whole Startup. Every [Interface](/business/nouns/interface) its Customers use answers there, under the Startup's [Brand](/business/nouns/brand):

```text
linguaroster.com          Site
linguaroster.com/docs     Docs, with llms.txt and Markdown per page
linguaroster.com/portal   Portal
linguaroster.com/api      API
linguaroster.com/mcp      MCP server
api.linguaroster.com      Alias of /api
```

That set is the Startup's [Publication](/business/nouns/publication), described in [what Customers see](/code/builders/software/publication). An Agent that knows the Domain finds the rest through `llms.txt` and `agents.json`. The Startup's own [Workers](/business/nouns/worker) and previews also reach it at `api.sb/linguaroster.com`, and no Customer is ever given that address.

## Next
- [Domain registration](/products/platform/domain-registration): owner of record, renewal tiers, locks and transfers.
- [DNS](/products/platform/dns): records as data, checked daily.
- [Publication](/code/builders/software/publication): everything a Customer meets.