Domains

#On a server, with no setup

A box on a server answers at once on a real name with a real certificate:

https://dashboard.203-0-113-7.sslip.io     the dashboard
https://shop.203-0-113-7.sslip.io          an app called shop

203-0-113-7 is the server's IPv4 address with dashes. sslip.io answers every name under it with that address, so there is nothing to set up. The certificates come from Let's Encrypt. tiffin domain shows where you are. A managed box works the same way under <name>.shiptiffin.app.

Any other name one level under the box's domain is free too, and works at once: Domains › Add domain with blog.<box domain> (or tiffin domains add <project> --domain blog.<box domain> --app web) adds blog to the app's routes, with no DNS to set. Names directly under shiptiffin.app belong to other boxes and are refused.

(A local box in a VM, for trying Tiffin out, uses *.tiffin.localhost and its own certificate authority: the CLI trusts it after tiffin up, browsers after tiffin trust. Real domains need a server.)

#Your own domain, in two records

At your DNS host, point the domain and everything under it at the server:

Add the same two as AAAA records if the server has IPv6 (tiffin domain lists its addresses). Then:

tiffin domain check --domain example.com   # optional: what DNS says now
tiffin domain set example.com

domain set checks both records first. If they don't point at the box yet, nothing changes and you get the exact records to add. When they do, the dashboard moves to dashboard.example.com and apps to <project>.example.com (other apps of a project to <project>-<app>.example.com). Want to keep example.com itself for something else? Use a subdomain: tiffin domain set apps.example.com (the records are then apps and *.apps).

tiffin domain unset goes back to the sslip.io name.

#The domain itself

example.com itself (not a name under it) sends visitors to the dashboard (https://dashboard.example.com/) until an app uses it. The same goes for a managed <name>.shiptiffin.app and for the automatic sslip.io name. It is a temporary redirect (302), so browsers don't remember it.

To put your website there, give it to an app:

tiffin domains add shop --domain example.com

The app wins as soon as the change applies, and tiffin domains remove shop example.com brings the redirect back. Settings › Domain in the dashboard shows which it is now, and so does tiffin domain.

#Apps on a domain of their own

Like vercel.com and vercel.app, the dashboard can live on one domain and the apps on another:

tiffin domain set example.com --apps-domain example.app

The dashboard, the API and webhooks stay at dashboard.example.com; apps, previews and the box's own service names (s3, files, t, errors, otel) move to <name>.example.app. App code then runs on a different registrable domain from the dashboard, so it cannot set cookies on the dashboard's domain. (The dashboard's sign-in cookie is host-only either way.) The records are:

(plus AAAA with IPv6). example.com itself is not needed, so it can stay your website. If it points at the box, it behaves as above, and example.app itself does too: it sends visitors to the dashboard, or to https://example.com/ when an app on the box serves example.com, until an app uses example.app itself. tiffin domain check --domain example.com --apps-domain example.app lists them and what DNS says now; with --create-records, the box adds the ones in zones your connected DNS provider holds and tells you exactly which to add by hand (a Cloudflare token for All zones holds both). A custom domain's CNAME then points at dashboard.example.com.

tiffin domain set is the whole setting: running it again without --apps-domain puts the apps back on the box domain. Either way the old app names keep working until the new certificates are live, then for an hour. Apps read the domain they live under from TIFFIN_DOMAIN, and their own address from TIFFIN_URL.

#A domain for one project

Give an app its own name, example.com or shop.example.com:

tiffin domains add shop --domain example.com --app web --www

This is a normal change: you see the plan, then confirm it. It adds "example.com" to the app's routes (and www: "redirect" under domains), so tiffin pull brings it into your tiffin.config.ts:

apps: {
  web: { routes: ["shop", "example.com"] },
  api: { routes: ["example.com/api"] },   // only /api goes to the api app
},
domains: { "example.com": { www: "redirect" } },

The answer lists the records to add: an A (and AAAA) record to the server, or, for a subdomain, one CNAME to the box's own domain. tiffin domains list shop shows each name's state:

• waiting_for_dns, with the reason ("points to 5.6.7.8, not this box", "no A or AAAA record yet"). The box checks again on its own: after 15 seconds, then less and less often, up to every 30 minutes. tiffin domains check shop example.com checks now.
• issuing: it points here; the certificate takes a few seconds.
• live.
• error, with what to do: a CAA record that doesn't allow Let's Encrypt, a rate limit, ports 80 and 443 closed.

tiffin domains remove shop example.com stops serving it. Your DNS records stay.

#Let Tiffin manage DNS (optional)

Connect a Cloudflare API token with Zone · DNS · Edit on your zones:

tiffin dns connect cloudflare --token <token>

The box checks the token by listing your zones and stores it encrypted. From then on:

• tiffin domain set example.com --create-records and tiffin domains add ... --create-records add the records for you (with the owner's or a box-wide key: the provider's zones are the box's, so a key for one project can't write to them);
• the box gets one wildcard certificate for *.example.com (DNS-01), so new apps and previews have HTTPS the moment they exist (for *.example.app with a separate apps domain, when the provider holds that zone; the dashboard then gets its own);
• records for email (SPF, DKIM, DMARC) can be set with tiffin dns records set.

Keep these records DNS only (grey cloud) in Cloudflare; the box serves HTTPS itself. tiffin dns disconnect cloudflare forgets the token.

#Behind the scenes

• The edge (Caddy) gets certificates from Let's Encrypt, with ZeroSSL as a fallback when you give an email (--email). They renew on their own, well before they expire.
• A certificate is only ever requested for a name the box serves. A project domain is handed over only once its DNS points here, so a domain you haven't set up yet never wastes Let's Encrypt's limits. Without a DNS provider, each app gets its certificate on its first visit. The domain itself gets one on its first visit too, for the redirect, and only while no app uses it; once an app does, it is checked like any project domain.
• Plain HTTP redirects to HTTPS. Browsers are told to stay on HTTPS (HSTS, 30 days) only for certificates from a public CA.
• A domain switch restarts the service for a few seconds (apps keep running). The old names keep working until the new ones have certificates, then for another hour. Passkey sign-ins belong to the dashboard's address: add them again on the new one.

#In the dashboard

• A project › Settings › Domains (also linked from the project's overview): add a domain, pick the app that shows it and whether www. comes along. The page lists the exact records to add, with a copy button for each, and watches DNS until the domain is live with HTTPS. With Cloudflare connected, one button adds the records.
• Settings › Your box › Domain: the box's address and where apps live, Use your own domain (optionally with Put apps on a domain of their own; check the two records, then switch; the page follows the dashboard to its new address) and Go back to the automatic address.
• Settings › DNS: connect Cloudflare with a token made from its Edit zone DNS template (All zones), see which domains it can manage, or disconnect.

For agents: GET /v1/domain, POST /v1/domain, GET /v1/projects/{project}/domains, POST /v1/projects/{project}/domains; the same names as MCP tools.