thelastapi
Get started free

Add a custom domain with automatic HTTPS

Add a custom domain with automatic HTTPS to your thelastapi project using `vibiz domains add` or the API, configure DNS, and SSL provisions itself.

On this page 9 sections

To add a custom domain with automatic HTTPS, run vibiz domains add yourdomain.com and point your DNS records to the provided targets. thelastapi automatically provisions and renews an SSL certificate as soon as your DNS records resolve. Your project remains accessible on its default <slug>.vibiz.app address while the custom domain and HTTPS certificates configure in the background.

This guide walks through connecting an existing domain, routing root domains and subdomains, confirming ownership, and verifying SSL certificate status.

How custom domains and automatic HTTPS work

Every thelastapi project gets a free web address: https://<slug>.vibiz.app. When you add a domain your business owns (shop.example.com or example.com), our hosting attaches it to your project while keeping the original address active.

Once you add a domain, the platform enters a resolution loop. As soon as the required DNS records appear publicly, an SSL certificate is generated and configured automatically. You do not need to configure web servers, generate private keys, or renew certificates manually.

After DNS, ownership verification, and HTTPS provision successfully, the new domain becomes the project's primary_url. In the console, the custom domain is displayed first, with <slug>.vibiz.app right beside it.

If you are setting up an application from scratch, you can review the Hosting documentation or see our guide on how to deploy a static site with one command.

Step 1: Add the domain to your project

From your project directory (where vibiz.json was generated by vibiz init), run the vibiz domains add command:

Terminal
vibiz domains add shop.example.com

The CLI prints the exact DNS records to configure at your registrar or DNS provider.

You can check the configuration state of all domains connected to the project at any time:

Terminal
vibiz domains

Each domain displays one of four statuses:

  • pending_dns: The system is waiting for your DNS records to appear.
  • verifying: The DNS records were detected; ownership confirmation and HTTPS certificate generation are underway.
  • active: The domain is live and serving traffic over HTTPS.
  • error: Something prevented setup; check the accompanying error message for specifics.

The platform automatically re-evaluates domain status when you check, rate-limited to once every 20 seconds. To bypass this timer and trigger an immediate lookup, run:

Terminal
vibiz domains verify shop.example.com

Step 2: Configure DNS records at your registrar

To direct traffic to your project, add the records returned by records_to_set where your domain's DNS is managed.

You connectRecord to addNameValue
a subdomain, shop.example.comCNAMEshopcname.vibiz.app
the domain itself, example.comA@the address records_to_set shows
…and its wwwCNAMEwwwcname.vibiz.app

Record names in records_to_set are relative to the zone. An @ symbol represents the domain root. Some DNS management interfaces do not use @ and require the full hostname (example.com or shop.example.com); both refer to the exact same location.

Handling apex domains and www redirects

When you attach a root apex domain like example.com, the platform automatically configures www.example.com as a permanent redirect to it. This ensures that visitors arrive at the same destination regardless of how they type your address, preserving search engine ranking and session consistency.

If your preference is to serve your site from the www subdomain as the primary address rather than the apex, connect www.example.com directly as a subdomain and do not connect the root domain.

Step 3: Verify ownership and sign-in trust

In specific cases—such as when a domain was previously deployed on another project—an extra TXT record is included in records_to_set. Enter the exact name and value at your DNS provider to confirm ownership.

Domains added directly by account owners, domains served by our hosting, or domains bought through thelastapi are automatically trusted for authentication. However, when an AI agent adds a domain on your behalf, session replay and analytics start recording immediately, but the domain displays:

Text
trusted_for_sign_in: false

This safeguard prevents unauthorized parties from routing authentication callbacks through unverified domains. To mark the domain as trusted for user logins:

  1. Add the provided trust_record TXT entry at your DNS provider. The record name will be formatted like _vibiz.shop.example.com with a value of vibiz-verify=….
  2. Run vibiz domains verify shop.example.com.

The system checks for this record once every hour for a week. Alternatively, the project owner can confirm the domain instantly in the console by navigating to Domains ▸ Trust for sign-in.

If you are setting up user accounts, see how to deploy a Next.js app with a database and sign-in in one command.

Managing domains with the HTTP API

Every action supported by the CLI is available over HTTP, allowing automation inside custom deployment scripts or CI pipelines.

To attach a domain to a project:

Terminal
curl -X POST https://thelastapi.dev/v1/projects/prj_123/domains \
  -H "Authorization: Bearer $VIBIZ_API_KEY" \
  -H "content-type: application/json" \
  -d '{"domain":"shop.example.com"}'

The endpoint responds with 201 Created containing the DNS requirements:

JSON
{
  "object": "project_domain",
  "domain": "shop.example.com",
  "status": "pending_dns",
  "records_to_set": [
    {
      "type": "CNAME",
      "name": "shop",
      "value": "cname.vibiz.app"
    }
  ],
  "console_url": "https://thelastapi.dev/projects/prj_123/domains"
}

To request an on-demand verification check over HTTP:

Terminal
curl -X POST https://thelastapi.dev/v1/projects/prj_123/domains/shop.example.com/verify \
  -H "Authorization: Bearer $VIBIZ_API_KEY"

To view all domains attached to a project:

Terminal
curl https://thelastapi.dev/v1/projects/prj_123/domains \
  -H "Authorization: Bearer $VIBIZ_API_KEY"

Instant setup with registered domains

If you want to skip manual DNS configuration entirely, you can buy a domain name with an API or one command. Domains purchased through thelastapi are registered directly to your saved owner details, billed from your account balance, and managed on our nameservers.

Terminal
vibiz domains search acmebakery
vibiz domains buy acmebakery.app

Because DNS is managed internally, attaching a purchased domain to any of your projects requires zero manual records:

Terminal
vibiz domains use acmebakery.app --project prj_123
vibiz domains use app.acmebakery.app --project prj_123

The domain bypasses pending_dns, attaches with dns_by_vibiz: true, and automatic HTTPS provisions within a minute or two. For details on registration rules and renewals, review the Domains documentation.

Monitoring domain health in Mission Control

thelastapi runs automated diagnostic checks on every active project roughly once an hour. You can inspect project health in the console under Mission Control or via the CLI:

Terminal
vibiz health

Under the Domain & HTTPS step, Mission Control runs two dedicated checks:

  • Site up: Fails if the primary address returns a 5xx error, times out after 10 seconds, does not resolve, or serves an invalid SSL certificate. It warns if / returns a 4xx error or if the address resolves over unencrypted HTTP.
  • Domain: Issues a warning whenever an attached custom domain is not yet active due to pending DNS records, ownership confirmation, or certificate issuance.

To trigger an immediate health evaluation across all account projects, run:

Terminal
vibiz health run

To learn more about tracking application uptime and revenue funnels, check the Mission Control and health checks docs.

Removing domains and managing constraints

A domain can only point to one project at a time. Attempting to attach a domain already in use on another project returns a 409 domain_taken error.

To disconnect a domain, run the removal command using a full-access key:

Terminal
vibiz domains remove shop.example.com

Removing a domain frees it up for use on another project immediately. If a project is deleted, attached domains remain reserved through the 7-day restore window before becoming available for other projects.

If you ever decide to host your application elsewhere, you can disconnect your domain and export your application assets at any time. The source code, environment guide, and PostgreSQL data snapshots are available via the Export documentation.

To begin hosting your projects, follow the setup steps in the Quickstart documentation or explore the cheapest way to host a website and database for a side project.

Frequently asked questions

How long does it take for automatic HTTPS to activate after adding DNS records?

Once your DNS records resolve across the public internet, certificate issuance and HTTPS configuration typically finish within two to three minutes. You can check the current status with `vibiz domains` or force an immediate re-check using `vibiz domains verify yourdomain.com`.

What happens if an AI agent attaches a custom domain to my project?

The domain is attached, traffic routes normally, and session replay and analytics begin collecting immediately. However, the domain is marked with `trusted_for_sign_in: false` until an owner confirms it in the console or the DNS owner adds the verification TXT record from `trust_record`.

Does adding a custom domain disable my free thelastapi address?

No, your original `https://<slug>.vibiz.app` address remains active and serves your site. Once your custom domain passes DNS and HTTPS verification, it becomes your project's `primary_url`, but the free URL continues to function.

Can I attach a domain if my app is hosted outside thelastapi?

Yes, you can run `vibiz domains add yourdomain.com --elsewhere`. This registers the domain with your project so analytics, session replay, and user sign-in accept traffic from it without expecting you to point DNS records to thelastapi hosting.