---
title: "Add a custom domain"
description: "Attach a hostname and verify DNS."
---

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

# Add a custom domain

Attach a hostname to an app, configure DNS using the returned records, then verify when propagation finishes.

### Add the domain

Create the domain on your app. The response includes `expectedDnsRecords` / `expected_dns_records` to add at your DNS provider. Set `isDefault` / `is_default` if this should be the app's primary hostname.

```javascript
const app = await client.apps.retrieve("da_XYZ");

const domain = await client.apps.domains.create({
  app: app.id,
  hostname: "www.example.com",
  isDefault: false, // true = primary hostname for this app
});
// Should return: {
//   "id": "alias_abc123",
//   "hostname": "www.example.com",
//   "url": "https://www.example.com",
//   "state": "UNVERIFIED",
//   "expectedDnsRecords": [
//     { "host": "www", "recordType": "CNAME", "value": "..." }
//   ]
// }
console.log(domain.id, domain.state, domain.expectedDnsRecords);
```

```python
domain = client.apps.domains.create(
    app="da_XYZ",
    hostname="www.example.com",
    is_default=False,  # True = primary hostname for this app
)
# Should return: {
#   "id": "alias_abc123",
#   "hostname": "www.example.com",
#   "url": "https://www.example.com",
#   "state": "UNVERIFIED",
#   "expected_dns_records": [
#     { "host": "www", "record_type": "CNAME", "value": "..." }
#   ]
# }
print(domain.id, domain.state, domain.expected_dns_records)
```

### Verify DNS

After DNS propagates, call `verify` with the domain `id`. Returns `true` when the hostname is verified.

```javascript
const verified = await client.apps.domains.verify(domain.id);
// Should return: true
console.log("verified:", verified);
```

```python
verified = client.apps.domains.verify(domain.id)
# Should return: True
print("verified:", verified)
```

> Source: [stackmachine/sdks](https://github.com/stackmachine/sdks/tree/main) examples.

Source: https://docs.stackmachine.com/apps/domains/add/index.mdx