Build and Host Your Company Website on Cargo With Your Own Domain

To build and host your company website on Cargo with your own domain, declare it as a statically exported Next.js app with defineApp, give it your www hostname, and publish the DNS records with defineDomain (or add them at your DNS provider): Cargo builds the app on deploy and serves every page as real HTML on your domain. The site then lives in your go-to-market repository, and every change, from a typo to a new page, is a pull request someone reviewed before it deploys.

The website-building cookbook is that setup as a worked example your coding agent adapts. This page explains what it does end to end, what it needs, what it costs and where it stops.

Deploy it #

npm install -g @cargo-ai/cli
cargo-ai login --email you@company.com

# a new project, with the cookbook in it
cargo-ai cdk init my-site --cookbook website-building && cd my-site && npm install

# or, inside an existing Cargo project
cargo-ai cdk add cookbook/website-building

cdk add copies the code to infra/website-building/ and the procedure to .claude/skills/website-building/, so the coding agent in that repository knows how to brief, build and ship the site. A new account starts with 100 free credits and needs no card.

Then, from the project root:

cargo-ai cdk plan     # shows the app, the hostname and the DNS diff record by record
cargo-ai cdk deploy   # only after you have read that diff

If the repository is connected to Cargo, the merged pull request is the deploy and you do not run deploy from a laptop.

How it works, end to end #

Three resources make the site, and nothing else is deployed:

1. The app. defineApp("website", { path, domains }) points at a Next.js package in the repository. On deploy, Cargo uploads it and runs its own build script: next build with output: "export" and trailingSlash: true, moved to dist/. The starter ships home and about pages, robots.txt, a sitemap, a theme toggle and shadcn/ui on Tailwind, with the copy in one site.json.
2. The hostname. domains: ["www.example.com"] attaches your www host on deploy. Cargo’s own *.app.getcargo.run URL and every preview URL answer with X-Robots-Tag: noindex, so your domain is the only origin search engines index.
3. The domain, when Cargo holds its DNS. defineDomain("example.com", { adopt: true, dnsRecords: [website.domainRecords], redirectUrl: "https://www.example.com" }) publishes the records the hostname needs (the _cargo-verify TXT, the certificate-validation CNAME and the www CNAME) and forwards the apex to www.

Cargo serves a path from the file the export wrote for it. For /pricing it serves pricing/index.html, then pricing.html, then your 404.html with status 404, and only then the root index.html. /pricing and /pricing/ resolve identically, and a prerendered page reaches a crawler with its own title, description and canonical in the initial HTML.

When your DNS is somewhere else #

Most company domains keep their DNS at a registrar or provider. In that case you delete infra/domains/website.ts, keep domains on the app, deploy once (not as a draft, which attaches no hostname) and add the three records by hand:

cargo-ai hosting app list    # the app's uuid

curl "https://api.getcargo.io/v1/hosting/custom-domains/list?appUuid=<app-uuid>" \
  -H "authorization: Bearer $CARGO_API_TOKEN"

verification holds the _cargo-verify TXT and the certificate-validation CNAME, and cnameTarget is where www points. Forward the apex to https://www.<domain> with the provider’s redirect. Cargo never writes a zone it does not hold.

What the deploy changes in your zone #

When Cargo holds the DNS, dnsRecords is merged into the live zone. Records the deploy did not write, MX, SPF, DKIM and DMARC included, stay where they are, so a domain your Cargo mailboxes send from can carry the website too. Two things are replaced rather than added: the www CNAME takes over whatever www pointed to, and redirectUrl replaces the apex forward. cargo-ai cdk plan reads the live zone and prints every +, ~ and - before anything changes.

The first deploy is the exception: the hostname attaches during it, so that plan cannot list the app’s records yet. If dig +short www.<domain> already answers, deploy in two steps (first without website.domainRecords, then with it), so the second plan shows the www change before it happens.

What it needs #

• A Cargo workspace and @cargo-ai/cli with @cargo-ai/cdk 1.0.92 or later, and Node.js 22.18 or later.
• A domain you control, and to know who holds its DNS.
• Approved copy. site.json starts as status: "draft", which keeps the pages noindex and robots.txt disallowing, until someone has reviewed them.

What it costs #

An app promoted to production is 50 credits a month, per the Cargo credits reference, and each merge is one deployment of it. Adopting a domain the workspace already owns adds no purchase. Registering a new one through Cargo charges workspace credits once and is not refundable: the plan’s + create domain: line is that purchase. Nothing in the cookbook runs on a schedule.

What it will not do #

• Run server code. Cargo hosts static files. Route handlers, middleware, image optimization and a form that delivers live elsewhere and are called from the page.
• Publish a draft or invented content. No made-up customers, numbers, prices or testimonials, and nothing ships as ready before review.
• Serve on the apex. The apex cannot CNAME to an app; it forwards to www.
• Go live the moment the deploy finishes. A hostname serves nothing until its _cargo-verify TXT resolves, which can take minutes to hours. A pending TXT is reported as pending.
• Take a live site off its name. Removing a hostname from domains leaves it attached; detaching is a deliberate action in Cargo.

Questions #

Deploy it from the website-building cookbook. For dashboards, internal tools and other hosted apps, see Cargo apps. Next on the same site: qualify and route demo requests in seconds.