Domains and addresses

A preview reaches the app either on its own hostnames or on Houseguest addresses. Both use the same agent; the choice is made per preview, in the first step of New preview.

	The app’s own hostnames	Houseguest™ addresses (hosted service)
Viewers use	app.lab.example.com	app.acme.houseguest.page
DNS work	A verified domain, and public DNS for each shared name	None
Public certificate logs show	The shared hostnames	Only your workspace’s wildcard, such as *.acme.houseguest.page
Works with	Any app, unchanged: cookies, redirects, cross-origin calls, its own sign-in	Apps that use relative links
Hostnames added later	Yes	No: open a new preview

The app’s own hostnames

Viewers use the address the app already has. Inside your network nothing changes: the same names keep resolving to the app through your internal DNS. Outside, public DNS for each shared name points at the edge.

Verify a domain

On the hosted service, a hostname is served on its own name only under a domain your workspace has verified. This stops another customer’s agent from claiming your names. A self-hosted edge needs no verification.

1. Domains & addresses → Add domain, for example lab.example.com (needs Manage domains).

2. At your public DNS provider, create the TXT record shown:

   _houseguest.lab.example.com.  TXT  "houseguest-verify=<value from the console>"

3. Check now. Houseguest also checks every 10 minutes for 7 days after you add the domain.

Rules:

• A verified domain covers itself and every name under it.
• Only one workspace can verify a domain. If a more specific domain is verified by another workspace (for example lab.example.com while you verified example.com), names under it belong to that workspace.
• A domain cannot be removed while an open preview uses a name under it.

The page shows each domain’s state and what the last check found: TXT record not found, TXT record found with another value, or public DNS did not answer.

Point hostnames at the edge

In the public zone that holds the name:

Record	Example	Use
CNAME to your target (preferred)	app.lab.example.com. CNAME acme.edge.houseguest.dev.	The usual choice. Your target is <short name>.edge.houseguest.dev, shown on Domains & addresses and the agent’s page
A record	app.lab.example.com. A <edge address>	Where a CNAME is not possible, such as a zone apex. The agent’s page shows the address to use
Wildcard	*.lab.example.com. CNAME acme.edge.houseguest.dev.	One record for every name under the domain

On a self-hosted edge the target is edge.<your domain>.

• Use DNS-only records. A CDN proxy in front (such as Cloudflare’s orange cloud) hides the edge, and the certificate cannot be issued.
• Do not add an AAAA (IPv6) record for a shared name.
• Internal DNS needs no change.

The agent’s page shows each hostname’s state: DNS ok, DNS missing, Points elsewhere or Not checked. Houseguest asks a public resolver, so your internal DNS does not affect it. A change can take a minute to show.

Certificates

The edge gets a certificate for each shared hostname from Let’s Encrypt (or ZeroSSL, when Let’s Encrypt fails) by itself, the first time it is needed, and renews it. You upload nothing. It does so only for a name that a connected agent of the owning workspace forwards and whose public DNS already points at the edge, so strangers cannot make the edge request certificates for names they point at it.

A wildcard DNS record does not mean a wildcard certificate: each name gets its own.

Certificate Transparency

Every publicly trusted certificate is recorded in public Certificate Transparency logs. A shared hostname such as app.lab.example.com therefore becomes publicly visible once its certificate is issued, even after the preview ends. If internal names must stay private, use Houseguest addresses: only the houseguest.page address appears in the logs.

Houseguest addresses

On the hosted service, a preview can use addresses under your workspace’s own name on houseguest.page, such as app.acme.houseguest.page, instead of the app’s own hostnames.

• No DNS changes, and no domain verification. Any name a connected agent forwards can be used.
• Internal names stay private. They never appear in public DNS or certificate logs. Your workspace has one wildcard certificate for all its addresses (*.acme.houseguest.page), so individual addresses do not appear in certificate logs either. A workspace’s first address can take 1 to 2.5 minutes to answer while that certificate is issued.
• One sign-in covers every address in the preview.
• Stable addresses. An internal name keeps its address across previews, so an app’s sign-in (SSO or OAuth) can allow it once as a redirect.

How it works: the edge sends each request to the agent under the internal name, and rewrites the address in the Origin, Referer, Location, CORS, Content-Security-Policy and cookie-domain headers. It never rewrites page content.

That decides which apps fit:

• Work well: apps that use relative links, or that build links from a configurable base URL or the X-Forwarded-Host header (which carries the address).
• Do not work: apps that write absolute links with their internal hostname into HTML, JavaScript or JSON. Those links point at the internal name and fail for viewers. Share such apps on their own hostnames.
• Sign-in inside the app (SSO, OAuth) needs the address added as an allowed redirect.

Domains & addresses → Houseguest addresses lists your workspace’s addresses with the internal name behind each, the agent that forwards it, the previews using it and whether it is Live or Idle, then the forwarded names with no address yet and the address each would get (Assigned on first use).

Your workspace’s short name is part of every address, so it cannot change once addresses exist.

Caution

houseguest.page is not yet on the Public Suffix List. Until it is, a page on another workspace’s address could set a cookie for all of houseguest.page. Houseguest’s own sign-in ignores such cookies; your app’s own cookies are not protected the same way until the listing is accepted.