Eyevinn Open Source Cloud allows you to assign custom domain names to applications deployed via the "My Apps" feature. This guide explains the three types of domains available and how to configure each one.

OSC supports three distinct domain types. Understanding the difference is important before you begin.

Managed domains are subdomains under the OSC platform domain. They are covered by a wildcard TLS certificate managed by the platform — no DNS configuration is required from you.

Managed domain patterns:

You choose the subdomain prefix; the platform ensures it is unique and provides automatic HTTPS.

Custom domains are domain names you own and control (e.g., myapp.example.com). They require:

• A paid OSC plan
• DNS configuration at your domain registrar (CNAME record pointing to the OSC load balancer)
• An individual Let's Encrypt certificate, which the platform provisions automatically once DNS is configured

Custom domains are not available on the free plan. The option is disabled in the web console unless your account is on a paid plan.

Wildcard domains map an entire subdomain namespace (e.g., *.pds.example.com) to a single service instance. They require:

• A paid OSC plan
• A wildcard TLS certificate in PEM format that you supply
• An A record in DNS pointing the wildcard entry to the platform's ingress IP (returned as dnsTarget after creation)

Unlike custom domains, OSC does not provision certificates for wildcard domains automatically — you obtain the certificate from any certificate authority and upload it. The platform stores and serves it. When the certificate approaches expiry, you can rotate it via the web console without any downtime.

When you deploy an application via My Apps without configuring a domain, it receives a default URL in this format:

https://<10-char-hash>.apps.osaas.io

The 10-character hash is a stable identifier derived from your tenant ID and application name. To get a friendlier URL like mycoolapp.apps.osaas.io instead, you can set up a managed domain — see "Setting Up a Managed Domain" below. Managed domain names are subject to availability; if your preferred subdomain is already taken, you will need to choose a different one.

Once a custom or managed domain is mapped to your application, the url field returned by list-my-apps, get-my-app, and the MCP tools reflects the mapped domain rather than the internal runner URL. This means callbacks, webhooks, OAuth redirect URIs, and CORS configurations that rely on the app URL will automatically point to the correct public-facing address after a domain is mapped.

• A deployed application in OSC via the My Apps dashboard
• For managed domains: any plan
• For custom domains: a paid OSC plan, a domain name you own, and access to your DNS provider's settings
• For wildcard domains: a paid OSC plan, a wildcard TLS certificate (PEM format) from a certificate authority, and access to your DNS provider's settings

Managed domains are the simplest option. No DNS changes are needed.

1. Navigate to My Apps
2. Click the Domains tab
3. Click Add Domain
4. Select Managed as the domain type
5. Enter your desired subdomain (e.g., my-app)
6. The full domain is shown in the UI (e.g., my-app.apps.osaas.io)
7. Select the instance to map to this domain
8. Click Add Domain to confirm

The domain is active immediately once created.

You can ask the OSC Architect to set up a managed domain:

"Create a managed domain my-app.apps.osaas.io for instance myapp of service eyevinn-web-runner"

Or use the MCP tool directly:

create-my-domain
  domain: "my-app.apps.osaas.io"
  instanceName: "myapp"
  serviceId: "eyevinn-web-runner"
  isManaged: true

Setting isManaged: true explicitly requests a platform-managed domain. When omitted, the platform infers the type from the domain pattern.

Note on serviceId: The serviceId identifies the runtime backing your app. For applications deployed via My Apps, use the correct service ID for your runtime:

• Node.js apps → eyevinn-web-runner
• Python apps → eyevinn-python-runner
• WebAssembly apps → eyevinn-wasm-runner

For catalog services, use the service ID shown on the service page at app.osaas.io. Each instance can only have one domain mapping — if the instance already has a domain, use update-my-domain instead.

Custom domains require DNS configuration in addition to the steps above.

1. Navigate to My Apps
2. Click the Domains tab
3. Click Add Domain
4. Select Custom as the domain type (requires a paid plan)
5. Enter your domain name (e.g., myapp.example.com)
6. Select the instance to map to this domain
7. Click Add Domain to confirm

After creation, the domain appears in the table with a Custom badge. Click the info icon next to it to see the DNS target you need to use.

"Create a custom domain myapp.example.com for instance myapp of service eyevinn-web-runner"

Or use the MCP tool directly:

create-my-domain
  domain: "myapp.example.com"
  instanceName: "myapp"
  serviceId: "eyevinn-web-runner"

The tool returns the domain details including the dnsTarget value you need for the next step.

After creating a custom domain, OSC returns a dnsTarget value. This is the hostname or IP address of the OSC load balancer, dynamically provided by the platform.

In the web console, you can retrieve this at any time by clicking the info icon next to the domain in the Domains tab.

Via MCP:

list-my-domains

The output for each custom domain includes a DNS Target line with the value to use.

In your domain registrar's DNS management panel:

1. Create a new CNAME record
2. Set the Name/Host to your subdomain (e.g., myapp for myapp.example.com)
3. Set the Value/Target to the DNS target shown in the OSC web console or returned by the API
4. Set TTL to 300 (5 minutes) is recommended initially

Example DNS record (using the target provided by OSC after domain creation):

Do not use a hardcoded hostname — always copy the actual dnsTarget value from OSC, as it reflects the live load balancer address.

DNS changes can take anywhere from a few minutes to 48 hours to propagate globally. Typically, it takes 5-15 minutes.

You can check propagation using:

# Check if your CNAME is resolving
dig myapp.example.com CNAME

# Or use nslookup
nslookup myapp.example.com

Once DNS is correctly configured, OSC automatically provisions an individual Let's Encrypt TLS certificate for your custom domain via cert-manager. Certificate provisioning typically takes 2-5 minutes after DNS propagation completes.

You can verify the certificate by visiting your custom domain in a browser:

https://myapp.example.com

The browser should show a valid SSL certificate without warnings.

Wildcard domains let you map an entire subdomain namespace (e.g., *.pds.example.com) to a single service instance. All requests matching the wildcard pattern are routed to that instance, regardless of the subdomain prefix. This is useful for multi-tenant applications where each tenant gets their own subdomain — for example, a Bluesky Personal Data Server where each user gets a handle under *.pds.example.com.

Wildcard domains require:

• A paid OSC plan
• A wildcard TLS certificate (PEM format) that you supply — OSC does not issue wildcard certificates automatically
• DNS configuration at your registrar (an A record pointing *.yourdomain.com to the platform's ingress IP)

Note: Wildcard domains differ from regular custom domains in two important ways. First, OSC provisions a Let's Encrypt certificate automatically for regular custom domains, but for wildcard domains you must provide your own certificate — Let's Encrypt wildcard certificates require DNS-01 challenge validation which OSC does not perform on your behalf. Second, wildcard domains require an A record in DNS (not a CNAME), because the platform returns an IP address as the dnsTarget for wildcard routing.

Get a wildcard TLS certificate from a certificate authority of your choice. Your certificate must:

• Cover the wildcard domain pattern (e.g., *.pds.example.com)
• Be in PEM format (.pem file containing the full certificate chain)
• Include a matching PEM-encoded private key

Certificate authorities that issue wildcard certificates include Let's Encrypt (via manual DNS-01 challenge with certbot --manual), ZeroSSL, DigiCert, and others.

1. Navigate to My Apps
2. Click the Domains tab
3. Click Add Domain
4. Select Wildcard as the domain type (requires a paid plan)
5. Enter your wildcard domain pattern (e.g., *.pds.example.com)
6. Select the target instance
7. Paste your PEM certificate and PEM private key in the respective fields
8. Click Add Domain to confirm

After creation, the domain appears in the table with a purple Wildcard chip. The table also shows the certificate expiry date, with a warning indicator if expiry is within 30 days.

Wildcard domain management is currently available via the web console. MCP tool support is planned for a future release.

OSC returns a dnsTarget value (an IP address) after creation. Copy this value — you need it for the next step.

In your domain registrar's DNS management panel, create a wildcard A record (not CNAME):

This routes all subdomains under pds.example.com to the OSC ingress IP.

Why an A record? For wildcard domains, the platform returns an IP address as the DNS target. An A record maps a hostname to an IP address directly. Unlike regular custom domains (which use a CNAME to a hostname), wildcard A records are widely supported by DNS providers for wildcard entries.

The web console shows each wildcard domain's certificate expiry date. When your certificate is approaching expiry, rotate it before it expires to avoid service interruption.

1. Navigate to My Apps
2. Click the Domains tab
3. Find the wildcard domain row and click Rotate Cert
4. Paste the new PEM certificate and PEM private key
5. Click Update to confirm

The new certificate is validated before the old one is replaced, ensuring continuity of service.

1. Navigate to My Apps
2. Click the Domains tab
3. Find the wildcard domain row and click Delete
4. Confirm the deletion

This removes the ingress, TLS secret, and domain record. After removal, also remove the wildcard DNS record from your registrar.

To change the domain mapped to an existing instance:

1. Navigate to My Apps and click the Domains tab
2. In the row for the domain you want to change, click Edit
3. Enter the new domain and confirm

update-my-domain
  instanceName: "myapp"
  domain: "newdomain.example.com"
  serviceId: "eyevinn-web-runner"

If switching to a custom domain, a new DNS target will be returned — update your DNS accordingly.

To remove a domain mapping from your application:

1. Navigate to My Apps and click the Domains tab
2. In the row for the domain you want to remove, click Delete
3. Confirm the deletion in the dialog

After removing the domain in OSC, also delete the corresponding DNS record from your registrar (for custom domains).

delete-my-domain
  serviceId: "eyevinn-web-runner"
  instanceName: "myapp"

All your domain mappings are listed in My Apps under the Domains tab. The table shows the domain name, instance name, service ID, and domain type. Wildcard domains are shown with a purple Wildcard chip. For wildcard domains, the certificate expiry date is also shown, with a warning indicator if expiry is within 30 days.

list-my-domains

Each domain entry in the output includes:

• isWildcard — whether the domain is a wildcard mapping
• expiresAt — certificate expiry date (for wildcard domains with tenant-supplied certificates)
• subjectAltNames — the Subject Alternative Names covered by the certificate

Before creating a managed domain, you can verify whether a subdomain is already taken.

check-domain-availability
  domain: "my-app.apps.osaas.io"

The tool returns whether the domain is available. If it is already in use by another tenant, you will need to choose a different subdomain.

Some DNS providers do not allow CNAME records on root domains (e.g., example.com without a subdomain). Options:

Some DNS providers (Cloudflare, DNSimple, NS1) support ALIAS or ANAME records that function like CNAME records for root domains. Use the DNS target from OSC as the value.

1. Configure www.example.com as a custom domain in OSC
2. Set up a redirect from example.com to www.example.com in your DNS provider's dashboard

Possible causes:

• DNS record not yet propagated
• CNAME target is incorrect
• Let's Encrypt certificate not yet provisioned

Steps to resolve:

1. Verify the DNS record using dig myapp.example.com CNAME
2. Confirm the CNAME value exactly matches the dnsTarget shown in the web console
3. Wait 5-10 minutes for certificate provisioning after DNS propagation completes

Possible causes:

• Domain not yet created in OSC
• Application instance not in a running state
• DNS not yet propagated

Steps to resolve:

1. Verify the domain mapping exists in the Domains tab
2. Check that the application instance is running in My Apps
3. Verify DNS propagation with dig or an online tool like https://dnschecker.org

Steps to resolve:

1. Reduce TTL to 300 seconds (5 minutes) if it is higher
2. Clear your local DNS cache:

   # macOS
   sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder
   
   # Windows
   ipconfig /flushdns
   
   # Linux
   sudo systemd-resolve --flush-caches

3. Test with a public DNS server (e.g., Google's 8.8.8.8) to confirm propagation

Possible causes:

• DNS A record not yet propagated
• A record points to the wrong IP (use the dnsTarget value returned by OSC exactly)
• Certificate does not cover the wildcard pattern (check subjectAltNames in the domain listing)

Steps to resolve:

1. Verify the A record using dig *.pds.example.com A (or a specific subdomain)
2. Confirm the value matches the IP in the OSC web console
3. Wait 5-15 minutes for DNS propagation

The Domains tab shows a warning indicator next to the certificate expiry date when expiry is within 30 days. Use the Rotate Cert button to upload a new certificate before the current one expires. Service continues uninterrupted during rotation.

Custom and wildcard domains require a paid OSC plan. If the Custom or Wildcard option is greyed out in the Add Domain dialog, your current plan does not include custom domains.

• Use subdomains rather than root domains to avoid CNAME limitations.
• Set a low TTL (300 seconds) initially so DNS changes take effect quickly.
• Once DNS is stable, you can increase TTL (e.g., 3600 seconds) for better caching.
• If you delete an application in OSC, also remove the DNS record at your registrar.
• Let's Encrypt certificates renew automatically. If a renewal fails, verify the DNS record still points to the correct target.
• For wildcard domains, monitor the certificate expiry date shown in the Domains tab. Rotate the certificate before it expires — the platform shows a warning indicator when expiry is within 30 days.

• All custom domains receive SSL/TLS certificates via Let's Encrypt automatically.
• Wildcard domains use the TLS certificate you provide. You are responsible for obtaining and renewing the certificate.
• HTTP requests are automatically redirected to HTTPS.
• The maximum request body size is 64MB.

• User Guide: Deploy or Publish Your Application - Application deployment methods
• User Guide: Publish Web Application - Detailed publishing guide
• Service: Web Runner - Running Node.js applications

If you encounter issues setting up a domain:

• Check the FAQ
• Ask in the GitHub Community Forum
• Join our Slack Channel for real-time support