Deployment Domains - MIOSA Docs

A Domain is a hostname that routes to a preview, a deployment, a computer, or an exact custom resource. For production deployments, always use the public_url returned by the API. Do not reconstruct hostnames in SDKs, CLIs, or frontends.

Domain layers

MIOSA keeps these layers separate:

Layer	URL shape	Purpose
Sandbox preview domain	`https://{port}-{sandbox_slug}.sandbox.{preview_domain}`	Mutable live previews while an agent/user is editing
Tenant deployment domain	`https://{deployment_slug}.{deployment_domain}`	Branded durable URLs for generated production apps
Managed fallback domain	`https://{deployment_slug}.{organization_slug}.miosa.app`	Always-available MIOSA-managed fallback
Exact custom domain	`https://customer-owned.example.com`	A customer’s chosen production domain attached to one deployment

ClinicIQ example:

Sandbox preview:   https://5173-abc123.sandbox.cliniciq.com
Deployment domain: https://lead-magnet.apps.cliniciq.com
Managed fallback:  https://lead-magnet.cliniciq.miosa.app
Custom domain:     https://newpatients.someclinic.com

Preview domains do not imply production deployment domains. Configure both if you want both surfaces branded.

Tenant deployment domains

Tenant deployment domains are configured separately from preview domains. The backend resolves settings["deployment_domain"] for durable app URLs and falls back to {organization_slug}.miosa.app when no deployment domain is configured.

Public tenant-level management routes for deployment domains are not exposed yet. Operators can configure the tenant setting; SDKs and CLIs should treat deployment public_url / url as authoritative.

Recommended white-label DNS:

Record type	Name	Value	Used for
`CNAME`	`*.sandbox`	`proxy.miosa.ai`	Sandbox port previews
`CNAME`	`*.apps`	`proxy.miosa.ai`	Durable generated apps

Exact custom domains

Exact custom domains attach a customer-owned hostname to one deployment:

Kind	Example	DNS record
Subdomain	`app.smiledental.test`	`CNAME` to the verification target
Apex	`smiledental.test`	`A`/`AAAA`, `ALIAS`, `ANAME`, or flattened `CNAME` depending on DNS provider
WWW alias	`www.smiledental.test`	`CNAME` to the verification target

The attach flow

Once verified and TLS-active, MIOSA routes the exact domain to the deployment’s active version. Exact custom domains take precedence over tenant deployment domains and MIOSA fallback URLs.

Redirect policy

For apex + www domains, set the redirect policy:

Policy	Result
`none`	Both apex and www serve independently
`apex_to_www`	`smiledental.test` redirects to `www.smiledental.test`
`www_to_apex`	`www.smiledental.test` redirects to `smiledental.test`

Configure at attach time or update later via PATCH /deployments/:id/domains/:domain_id.

What changing a domain does

Changing a domain mapping:

Updates MIOSA’s route table.
Takes effect within seconds.
Does not rebuild the app.
Does not involve the source sandbox.
Does not require users to change the deployment ID.

This is why rollback is fast: only the deployment’s active version/route changes.

DNS verification edge cases

Situation	Behavior
CNAME points to the wrong host	Verification fails with `dns_target_mismatch`. Show the expected target.
TXT record not propagated yet	Verification fails with `dns_propagation_pending`. Retry after a few minutes.
User typos the domain	Verification fails with `dns_resolution_error`. Domain stays pending.
Domain already attached to another deployment in your tenant	`409 Conflict`. Detach from the other deployment first.
Domain attached to a different tenant	`403 Forbidden`. Contact support for transfer.

White-label checklist

For a platform like ClinicIQ:

Configure the organization slug (cliniciq).
Configure sandbox preview DNS, for example *.sandbox.cliniciq.com.
Configure tenant deployment DNS, for example *.apps.cliniciq.com.
Publish generated apps and display the returned deployment public_url.
Attach exact customer domains only when a clinic brings its own domain.