App URLs and Custom Domains on Varity

Varity Team Core Contributors Updated August 2026

Every Varity deployment gets a public URL based on its hosting type: static apps are served at https://varity.app/{name}/, and dynamic apps get their own subdomain at https://{name}.varity.app/. You can also attach your own domain to a deployment. This guide covers both.

How Your Domain Is Assigned

When you run varitykit app deploy, Varity registers a name for your app from your project’s name. The resulting URL depends on hosting type:

# Static apps: served on a sub-path
https://varity.app/{your-app-name}/

# Dynamic apps: served on their own subdomain
https://{your-app-name}.varity.app/

Your app name is derived from the name field in your package.json by default. You can override it with the --name flag.

Set a Custom App Name

Pass --name to choose your subdomain at deploy time:

varitykit app deploy --name my-app

Your app will be available at the URL for its hosting type:

# Static app
https://varity.app/my-app/

# Dynamic app
https://my-app.varity.app/

Naming rules

• Lowercase letters, numbers, and hyphens only
• 3-48 characters
• Must be unique across all Varity apps (first to register a name owns it)
• Cannot start or end with a hyphen

Tip

Claim your name early. Subdomain names are first-come, first-served. Once you’ve registered a name, it’s yours as long as you have an active deployment.

Attach Your Own Domain

You can point a domain you own at a deployment. Both subdomains (app.example.com) and root domains (example.com) are supported.

Note

A deployment must serve a public web endpoint to take a custom domain, and each deployment holds one custom hostname at a time. Remove the current hostname before attaching a different one.

From the developer portal

1. Open your deployment in the dashboard and find the Custom domain card.

2. Enter the hostname you want to use and attach it. Varity responds with the exact DNS records to create.

3. Create those records at your DNS provider, then return to the card and run the verification check.

From the API

Attach a hostname with PUT /deployments/{deployment_id}/domain:

curl -X PUT https://varity.app/api/deployments/$DEPLOYMENT_ID/domain \
  -H "Authorization: Bearer $VARITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hostname": "app.example.com"}'

Read the current state at any time:

curl https://varity.app/api/deployments/$DEPLOYMENT_ID/domain \
  -H "Authorization: Bearer $VARITY_API_KEY"

The response tells you whether the deployment supports a custom domain, and returns the record it is waiting for:

{
  "supported": true,
  "domain": {
    "hostname": "app.example.com",
    "recordType": "cname",
    "recordName": "app",
    "expectedCname": "your-app.varity.app",
    "state": "pending_dns",
    "dns": { "status": "pending" },
    "certificate": { "status": "pending" },
    "serving": { "status": "pending" }
  }
}

Create the DNS Records

The records depend on whether you are attaching a subdomain or a root domain. Use the values returned by the API rather than copying the examples below.

Subdomain

A subdomain routes with a single CNAME record pointing at the value in expectedCname:

Type	Name (Host)	Value
CNAME	app	expectedCname

Root domain

A root domain cannot hold a CNAME, so it takes an A record pointing at expectedA, plus the TXT record in challenge that proves the zone is yours. Both are required:

Type	Name (Host)	Value
A	@	expectedA
TXT	challenge.name	challenge.value

Caution

Enter the Host field relative to your zone. Registrars append the zone automatically, so the Host for app.example.com inside the zone example.com is app, not app.example.com. Varity returns the correct value in recordName, using @ for a root domain.

Wildcard hostnames, IP addresses, and reserved or private-suffix hosts cannot be attached.

Verify the Domain

After the records are live, ask Varity to observe DNS and confirm the domain serves over HTTPS:

curl -X POST https://varity.app/api/deployments/$DEPLOYMENT_ID/domain/verify \
  -H "Authorization: Bearer $VARITY_API_KEY"

The domain moves through these states:

state	Meaning
pending_dns	Waiting for your DNS records to resolve to the expected values
certificate_pending	DNS is verified; the certificate is being issued
active	The domain is serving your app over HTTPS
error	A check failed; see errorCode

The dns, certificate, and serving blocks each carry their own status and checkedAt, so you can see which stage is outstanding. When DNS resolves to something other than the expected value, dns.status is mismatch and the observedCnames, observedA, and observedTxt fields show what Varity actually saw. That is usually the fastest way to spot a typo or a record left in place from a previous host.

Two error codes are reported: dns_lookup_failed when the records cannot be resolved, and https_verification_failed when the hostname does not yet serve over HTTPS.

Tip

DNS changes take time to propagate. If verification fails immediately after you create the records, wait for your provider’s TTL to expire and run it again.

Remove a Domain

Detach the hostname to free it for another deployment:

curl -X DELETE https://varity.app/api/deployments/$DEPLOYMENT_ID/domain \
  -H "Authorization: Bearer $VARITY_API_KEY"

Your app stays reachable at its varity.app URL.

View Your Registered Names

List the varity.app names registered to your account:

varitykit domains list

Output:

Your Domains (2)
┌─────────────┬──────────────────────────────────┬──────────────────┐
│ Subdomain   │ App URL                          │ App Name         │
├─────────────┼──────────────────────────────────┼──────────────────┤
│ my-app      │ https://varity.app/my-app        │ my-app           │
│ my-other    │ https://varity.app/my-other      │ my-other-project │
└─────────────┴──────────────────────────────────┴──────────────────┘

Tip

You must be logged in to list your names. Run varitykit login first if you see a “Not logged in” message.

Redeploy Under the Same Name

Redeploying with the same --name updates the existing deployment at that URL. Your domain stays the same:

# First deploy
varitykit app deploy --name my-app

# Update the app: same URL, no re-registration needed
varitykit app deploy --name my-app

An attached custom domain survives a redeploy. You do not need to re-create the DNS records.

SSL / HTTPS

All varity.app subdomains are served over HTTPS automatically, and certificates for attached custom domains are issued and renewed by Varity once DNS is verified. No certificate setup is required in either case.

Related

• Deploy Your App: full deployment guide
• CLI Reference: deploy: all app deploy flags
• API Reference: the full public platform API