Skip to content
Jiayang Cloud Docs

Custom domains

Every app has its own address under jiayang-apps.cloud. A custom domain lets the same app answer on a hostname you own as well, such as app.example.com. People reach it there in exactly the same way: they sign in, and the app’s sharing decides who gets in.

Plans

Section titled “Plans”

Custom domains are counted per workspace, pending and active together.

Plan Custom domains
Free None
Team 3
Business 5
Enterprise 5

For more, write to sales@jiayang.cloud. Adding one past your plan’s limit is refused with 403, and the refusal says which plan allows more, with the code plan_limit, or on Business, to talk to us about Enterprise, with the code contact_sales. If your workspace moves to a plan with fewer, its oldest verified domains keep working, as many as the new plan allows, and the rest stop until you remove some or move back.

A workspace can add up to 20 domains an hour.

Add a domain

Section titled “Add a domain”

You need to be an owner of the app, or an owner or admin of the workspace.

In the dashboard, open the app’s Settings tab and type the hostname under Custom domains. Or use the CLI:

Terminal window
jiayang domain add acme/hello app.example.com
Added app.example.com. Add these records at your DNS provider:


  CNAME  app.example.com  domains.jiayang-apps.cloud
  TXT    _jiayang.app.example.com  jiayang-verify=5f0c2e8a9d41b7360a1e4c9b2d87f513


It works at https://app.example.com once we've verified them, usually within a few minutes. Check with `jiayang domain list`.

Add both records at the DNS provider for example.com, exactly as shown:

  • The CNAME record sends the hostname’s traffic to us.
  • The TXT record at _jiayang. and your hostname proves the name is yours. Its value is new every time a domain is added, so records left from an earlier owner, or from an earlier add of yours, prove nothing.

Nothing about the name goes to our certificate provider until we’ve seen the TXT record. After that, a third record sometimes appears in the list, a TXT for the certificate. Add it too if it’s listed.

Keep the TXT record for as long as you use the domain. We look for it again once a day, and a domain whose record has been gone for 3 days fails. That way whoever runs the name’s DNS always decides which app it reaches.

DNS answers are cached. If we looked for the TXT record before you added it, it can take up to your DNS provider’s negative caching time, often an hour, before we see it.

An apex domain such as example.com can’t have a CNAME record in standard DNS. Use a DNS provider that offers CNAME flattening or an ALIAS record, and point it at domains.jiayang-apps.cloud. Or use a subdomain like www.example.com or app.example.com.

Check its status

Section titled “Check its status”
Terminal window
jiayang domain list acme/hello

A domain is in one of three states:

  • pending: we’re waiting to see the DNS records. We check about once a minute, and the list shows the records again until they’re seen. First we look for the TXT record, then for the CNAME and the certificate. Once the certificate is issued, the domain becomes active.
  • active: the app answers on it.
  • failed: it doesn’t reach the app, and the list says why.

A domain that isn’t verified within 7 days fails. Adding a domain doesn’t reserve the name: another workspace can add the same hostname, and whichever proves it first with its TXT record has it. The others fail with “Another workspace proved it owns this hostname first.”

We keep checking active domains too. If the hostname’s DNS stops pointing at us, or the certificate can’t be renewed for 7 days, the domain fails and stops reaching the app.

The dashboard’s Custom domains list updates by itself while a domain is pending.

Sign-in and sharing

Section titled “Sign-in and sharing”

A custom domain is a second address for the same app. The same people can open it, with the same roles, and your app gets the same identity token from the SDK as on its own address. It’s for people in a browser: bypass tokens, CLI sessions and agents call the app through the apps domain only, and a custom domain refuses their credentials.

Sign-in is per address. The first time someone opens the custom domain, we send them to sign in and bring them back, as on the app’s own address. Their session there is for that hostname only: it doesn’t sign them in on the app’s own address, and a session from the app’s own address doesn’t work on the custom domain. A session made before the domain was verified for this app, for example while the hostname belonged to another app, doesn’t work either: it’s ended, and the person is asked to sign in again.

Someone turned away on a custom domain can ask for access from the page they see, as on the app’s own address. Owners and admins see each app’s verified custom domains in the workspace’s list of apps and its CSV, and the workspace export lists every one with its status.

An app’s own outbound requests can’t reach a custom domain, as they can’t reach another app’s own address.

Remove a domain

Section titled “Remove a domain”
Terminal window
jiayang domain remove acme/hello app.example.com
Removed app.example.com. It stops working within 60 seconds.

Or use Remove next to it in the dashboard. You can remove a domain even while your workspace is suspended. You can then delete the DNS records. A removed hostname can be added again at once, by you or by anyone who proves they own it with a new TXT record.

A deleted app keeps its custom domains while it can be restored, and nobody else can add them in the meantime. Restored, it answers on them again. Once a deleted app or workspace is gone for good, its domains are removed, and the audit log records each one.

Names we refuse

Section titled “Names we refuse”
  • Our own domains: jiayang.cloud, jiayang-apps.cloud and anything under them.
  • IP addresses, ports, paths and wildcards like *.example.com. Add each hostname on its own.
  • Public suffixes that nobody owns, like co.uk or github.io, and names on a domain that can’t be registered.
  • A hostname another app already has.