opencloudportDomains
Serve an app at a domain you own, with a certificate made for you.
An app always answers at its own address. You can also give it addresses of your own:
- A custom domain you own, like
shop.example.com. Up to 20 per app. - A platform address,
<name>.<your platform domain>, if your workspace runs many apps for your own customers (for examplebakery.yourapps.com). One per app.
Each one gets a certificate automatically once its DNS points at opencloudport. Until then it's pending.
Add a custom domain
In the dashboard, open the app, go to Settings, and add the domain under Domains. Or with the API:
curl -X POST https://opencloudport.com/api/v1/apps/$APP_ID/domains \
-H "authorization: Bearer $OCP_KEY" \
-H "content-type: application/json" \
-d '{ "hostname": "shop.example.com" }'const domain = await ocp.app(appId).domains.add('shop.example.com')
console.log(domain.records) // what to add at your DNS providerThe answer lists the DNS records to add at your domain's DNS provider:
| Record | What it's for |
|---|---|
CNAME shop.example.com → <target> | Points the domain at your app. Required. |
TXT … (sometimes) | Proves you own the domain, so it can go live before you switch traffic over. Optional. |
- For a root domain (
example.comrather thanwww.example.com), most DNS providers don't allow a CNAME. Use their CNAME flattening or ALIAS record instead, or serve the app atwww. - It usually goes live within a few minutes of the record being in place, sometimes up to a day while DNS catches up. The dashboard checks every few seconds while it's open; the API checks again each time you ask.
- A domain can only belong to one app at a time.
Statuses
| Status | Meaning |
|---|---|
pending | Waiting for the domain to point here, or for its certificate. Visitors don't reach the app at it yet. |
active | Live, with a certificate. |
failed | It couldn't be set up (for example, the certificate timed out). Check the records, then remove it and add it again. |
ssl_status says the same for the certificate on its own, and message explains the status in plain words.
Platform addresses
If you run many apps under your own name (each of your customers gets an app), set a platform domain for the workspace once, then give each app a short name:
await ocp.appsDomain.set('yourapps.com') // once for the workspace
await ocp.app(appId).setSlug('bakery') // bakery.yourapps.comThen add one DNS record for the whole platform domain, from the records the first call returns:
CNAME *.yourapps.com → <target>- Names are unique in the workspace. Giving an app a new name replaces its old address;
clearSlug()removes it. - Changing the platform domain moves every app's address to the new domain. Removing it removes them all.
- Nobody else can add a custom domain under your platform domain.
API
| Method | Path | |
|---|---|---|
GET | /api/v1/apps/:id/domains | The app's domains, pending ones checked again first. |
POST | /api/v1/apps/:id/domains | { hostname } → 201, pending, with records. |
GET | /api/v1/apps/:id/domains/:domainId | One domain, checked again if pending. |
DELETE | /api/v1/apps/:id/domains/:domainId | Stop serving a custom domain. |
PUT / DELETE | /api/v1/apps/:id/slug | { slug }: set or remove the app's platform address. |
GET / PUT / DELETE | /api/v1/apps-domain | { domain }: the workspace's platform domain, and the record to add. Workspace keys only. |
AI agents get the same through the add_domain, list_domains and remove_domain tools.
Cost
Adding domains costs nothing today.