Deployment Domains

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:

Lumen example:

Sandbox preview:   https://5173-abc123.sandbox.lumen.app
Deployment domain: https://lead-magnet.apps.lumen.app
Managed fallback:  https://lead-magnet.lumen.miosa.app
Custom domain:     https://portal.acme.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:

Exact custom domains

Exact custom domains attach a customer-owned hostname to one deployment. Custom domains are enabled by plan: Business and Enterprise get them without a support ticket, and Developer does not include them.

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:

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

Provider input fields

DNS providers label the same fields differently.

Use the exact values MIOSA returns and translate only the field name:

Do not enter https://, a path, or a trailing slash in a DNS target.

Disable provider proxying until MIOSA reports that ownership and TLS verification are complete.

Verification sequence

If DNS resolves but the page still fails, continue with the Recovery Playbooks instead of changing records repeatedly.

White-label checklist

For a platform like Lumen:

1. Configure the organization slug (lumen).
2. Configure sandbox preview DNS, for example *.sandbox.lumen.app.
3. Configure tenant deployment DNS, for example *.apps.lumen.app.
4. Publish generated apps and display the returned deployment public_url.
5. Attach exact customer domains only when a customer brings its own domain.

Set up a custom domain in the dashboard

Connect your own domain - for example app.lumen.app - so users land on your brand rather than a MIOSA fallback URL.

Go to Settings → Domains and click + Add custom domain. The wizard walks you through three steps:

1. Enter your domain (app.example.com - no https://, no trailing path).
2. Add the DNS records shown to your domain provider.
3. Click Continue to verify - MIOSA checks your DNS and activates the domain.

You can also register the domain through the exact deployment or computer domain APIs before sending traffic; MIOSA returns the DNS records and verification status.

Required DNS records

For wildcard preview or app domains, delegate traffic to MIOSA:

Replace yourdomain.com with the apex domain you own (e.g. lumen.app if your custom domain is app.lumen.app).

Apex domains (no subdomain, e.g. lumen.app directly) additionally require an A/ALIAS record - add _miosa-verify.lumen.app TXT <token> as shown in the wizard.

TLS certificates and propagation

Certificates are provisioned automatically once DNS propagates. There is nothing to upload. You will see a valid https:// certificate on first browser visit.

DNS changes typically take 5-30 minutes but can take up to 48 hours depending on your provider’s TTL settings.

To check current propagation status:

dig *.yourdomain.com CNAME +short

The expected result is proxy.miosa.ai.

Once configured and verified, MIOSA’s router confirms the hostname belongs to your tenant, workspace, project, computer, or deployment, issues or reuses the TLS certificate, and routes the request to the current sandbox, computer, standard deployment, or App Engine container. Domain ownership and tenant scope are checked before MIOSA routes traffic.

Troubleshooting a routed domain

Verification fails immediately after adding records - DNS propagation is not instant. Wait a few minutes and click Retry verification in the wizard. The wizard polls every 5 seconds while open.

dig shows the right value but verification still fails - Some DNS providers add extra trailing dots or spaces. Ensure the CNAME value is exactly proxy.miosa.ai with no extra characters.

Cache flush - If the record still shows the old value, flush your local DNS cache:

# macOS
sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

# Linux (systemd-resolved)
sudo systemd-resolve --flush-caches

Or check propagation from a neutral vantage point using dnschecker.org.

My sandbox URL returns a TLS error or cert warning - DNS hasn’t propagated yet, or (on Cloudflare) the proxy status is not DNS only. Confirm the record with dig +short "*.your-domain.com" CNAME (expected proxy.miosa.ai.).

My sandbox URL returns 502 or 503 - Your sandbox isn’t running, or no HTTP server is listening on the port you’re requesting. The DNS chain is correct; the sandbox just needs to serve traffic.

My sandbox URL returns 400 or “URL not connected” - The slug doesn’t match any sandbox in your tenant. Confirm the sandbox is in running state and that the slug (first 8 hex chars of the sandbox UUID) matches the leftmost label of the hostname.

Branding

Once your domain is connected, customize the app name, logo, accent color, and favicon at Settings → General → Branding. The Domains page shows a live preview of what your users will see.

Disconnecting

To stop using your custom domain: remove the CNAME from your DNS provider, or open Settings → Domains in MIOSA and click Disconnect. After disconnecting, the next request to <slug>.<your-domain> will fail to issue a certificate. The domain becomes available to bind to a different tenant after the cache expires.

White-label checklist

• Publishing: how public_url is returned
• Versions: what the domain points at
• Rollback: repointing the deployment at an older version
• White-label setup: setup order for platforms