Domains — MIOSA Docs

A Domain is a hostname that routes to a deployment. MIOSA gives every deployment a managed URL by default, and lets you attach custom domains with automatic Let’s Encrypt TLS.

Managed URLs

Every deployment gets a managed hostname at creation:


<deployment-slug>.<organization-slug>.miosa.app

Example: smile-dental.cliniciq.miosa.app. TLS is provisioned automatically against the wildcard cert.

If you configure a preview base domain, managed deployment URLs inherit it:

Scope	Example URL
Organization preview domain `cliniciq.dev`	`https://smile-dental.cliniciq.dev`
Workspace preview domain `drsmithclinic.com`	`https://smile-dental.drsmithclinic.com`
Project preview domain `program.drsmithclinic.com`	`https://smile-dental.program.drsmithclinic.com`

Precedence is project → workspace → organization → MIOSA fallback. Exact deployment custom domains still take priority over these managed URLs.

You can rename the deployment slug if needed (subject to uniqueness in your workspace). Renaming retires the old hostname; existing TLS for the old name continues to serve until its current cert expires.

Custom domains

Three flavors of custom domain:

Kind	Example	DNS record
Subdomain	`app.smiledental.test`	`CNAME` to the verification target
Apex	`smiledental.test`	`A` records to MIOSA’s anycast IPs, or `ALIAS`/`ANAME` if your DNS provider supports it
Wildcard	`*.smiledental.test`	More involved — see “Wildcards” below

The attach flow

Once verified and TLS-active, MIOSA routes the domain to the deployment’s active version.

Redirect policy

For apex + www domains, set the redirect policy:

Policy	Result
`none`	Both apex and www serve independently (you’d need to add www separately)
`apex_to_www`	`smiledental.test` 301-redirects to `www.smiledental.test`
`www_to_apex`	`www.smiledental.test` 301-redirects to `smiledental.test`

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

What changing a domain does (and doesn’t) do

Changing a domain mapping:

Updates a row in MIOSA’s route table.
Takes effect within seconds (the edge proxy caches the route table with a short TTL).
Does not rebuild the app.
Does not restart runtime instances.

This is why rollback is trivial: the runtime instances are already running the old version; only the route mapping changes.

DNS verification edge cases

Situation	Behavior
CNAME points to the wrong host	Verification fails with `dns_target_mismatch`. Show the user the expected target.
TXT record not propagated yet	Verification fails with `dns_propagation_pending`. Retry after a few minutes — DNS TTL applies.
User typos the domain	Verification fails with `dns_resolution_error`. Domain stays in `pending` state.
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. Each domain belongs to at most one tenant. Contact support for transfer.

Wildcards

Wildcards (*.smiledental.test) require DNS-01 challenges, which means MIOSA needs to update DNS records on your domain in real time during cert issuance. Two ways:

Delegate the subdomain to MIOSA. Set NS records on smiledental.test pointing at MIOSA’s nameservers for the subdomain you want wildcarded.
Bring your own DNS provider. Some providers expose API access for ACME DNS-01 — MIOSA can integrate (currently Route53 and Cloudflare; more on request).

Wildcards are typically only needed for white-label platforms serving per-end-user subdomains. For single-app deployments, regular CNAME + cert is simpler.

White-label managed URLs

If you’re building a platform and want your customers to see branded preview / deployment URLs, set preview domains through the API:

PUT /api/v1/tenant/preview-domain
PUT /api/v1/workspaces/{id}/preview-domain
PUT /api/v1/projects/{id}/preview-domain

Each preview base domain needs two wildcard CNAME records:

Record type	Name	Value	Used for
`CNAME`	`*`	`proxy.miosa.ai`	Managed deployments, computers, and default previews
`CNAME`	`*.sandbox`	`proxy.miosa.ai`	Port-qualified sandbox previews

Edge cache and the route table

The route table (domain → active_version_id) is cached at MIOSA’s edge with a short TTL (default 60s). This is what makes the routing layer resilient: if MIOSA’s control plane has a brief outage, the edge keeps serving the last known route table. Customers’ production stays up.

Trade-off: changes take up to TTL seconds to propagate everywhere. For most workflows that’s fine. Force-invalidate by hitting POST /api/v1/deployments/:id/route-refresh if you need an immediate update (this is rate-limited per tenant).