Custom domains

Custom domains let you serve your organization's functions from your own hostname (e.g. api.example.com). This feature is available on the Pro plan only.

Overview

• One custom domain per organization — You can add a single hostname; it must be unique across the platform.
• Traffic — After the domain is verified, requests to your hostname are routed to your organization's functions the same way as {your-project}.fold.run.
• CNAME target — You point your hostname to fold.run (or the target returned by the API).

Requirements

• Pro plan — Your organization must have an active Pro subscription. Adding or managing a custom domain on Free returns 403 with PRO_PLAN_REQUIRED.
• DNS access — You need permission to create a CNAME record for the hostname.
• No fold.run hostnames — You cannot use fold.run or any *.fold.run subdomain as a custom domain.

Add a domain (POST /custom-domains)

curl -X POST https://api.fold.run/custom-domains \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "hostname": "api.example.com" }'

Field	Type	Required	Description
hostname	string	Yes	The custom domain (e.g. api.example.com)

Response (201):

{
  "hostname": "api.example.com",
  "status": "pending",
  "cname_target": "fold.run",
  "platform_hostname_id": "h_abc123",
  "ssl_status": null
}

Error code	Status	Description
PRO_PLAN_REQUIRED	403	Organization is not on the Pro plan
VALIDATION_ERROR	400	Invalid hostname or fold.run subdomain
CUSTOM_DOMAIN_ALREADY_EXISTS	409	Hostname is already in use by another organization

DNS setup (CNAME)

Create a CNAME record for your hostname pointing to:

fold.run

For example, to set up api.example.com:

Type	Name	Target
CNAME	api	fold.run

After DNS propagates, verify the domain (see below) to activate it.

Check status (GET /custom-domains)

curl "https://api.fold.run/custom-domains" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200):

{
  "hostname": "api.example.com",
  "status": "active",
  "cname_target": "fold.run",
  "platform_hostname_id": "h_abc123",
  "ssl_status": "active"
}

Status values:

Status	Description
pending	Domain added, awaiting DNS verification
pending_validation	DNS detected, SSL certificate being provisioned
active	Domain is live and serving traffic
error	Verification failed — check your DNS records

When the status is pending, a GET request automatically refreshes the status from the platform. If the domain has become active, the response reflects the updated status immediately.

If no custom domain is configured, all fields return null.

Verify domain (POST /custom-domains/verify)

Force a status refresh after updating DNS:

curl -X POST "https://api.fold.run/custom-domains/verify" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200): Same shape as the status response above, with the latest status.

Error code	Status	Description
CUSTOM_DOMAIN_NOT_FOUND	404	No custom domain configured for this organization

Remove a domain (DELETE /custom-domains)

curl -X DELETE "https://api.fold.run/custom-domains" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200):

{
  "hostname": "api.example.com",
  "status": null,
  "cname_target": "fold.run",
  "platform_hostname_id": null
}

After removal, the hostname stops routing to your organization. You can safely remove the CNAME record from your DNS.

Via the CLI

# Add a custom domain
fold domains add api.example.com

# Check status
fold domains status

# Verify (refresh after DNS change)
fold domains verify

# Remove
fold domains remove

Dashboard

You can add, view status, verify, and remove a custom domain from the dashboard at app.fold.run/console/domains.

Workspace subdomains

When your account has multiple workspaces, the platform automatically provisions a wildcard hostname (*.{your-slug}.fold.run) so each workspace gets its own subdomain:

staging.acme.fold.run/my-function    # staging workspace
production.acme.fold.run/my-function # production workspace
acme.fold.run/my-function            # default workspace

The wildcard hostname is provisioned automatically when you create your second workspace and removed if you go back to a single workspace. No DNS configuration is needed — this is handled entirely by the platform.

See Workspaces for more details on workspace URL routing.

SSL certificates

SSL certificates are provisioned automatically when your domain becomes active. No manual configuration is needed — the platform handles certificate issuance and renewal. The ssl_status field in the status response tracks certificate provisioning progress.