How it works

Your network dials out. The edge decides every request.

Nothing connects into your network. The agent holds one outbound connection, and forwards only the hostnames listed on its own host.

The parts

Part	Runs	Does
Agent	Inside your network, as a Docker container or a systemd service	Holds one outbound connection to the edge. Forwards only the hostnames and TCP services on its own allow-list, to the internal addresses you give it
Edge	Houseguest™’s servers (hosted), or a Linux server you run (self-hosted)	Gets a certificate for each shared hostname (one per workspace for Houseguest addresses), checks every request against the open previews, and sends allowed ones down the agent’s connection
Console	Next to the edge	Where admins connect agents and invite members, and sharers open and run previews
Viewer	Any browser	Signs in with an emailed code. Needs no account and installs nothing (the houseguest command line is only for TCP services)

A request, step by step

1. The agent joins once. An admin creates a join token in the console and runs the install command it shows. On first start the agent makes its own key pair and registers the public key with the token, which then stops working. Every later connection is signed with that key.
2. A sharer opens a preview. They pick hostnames the agent forwards, choose invites or standing access, and set how long it stays open.
3. A viewer arrives. They open the app’s address (or the invite link). With no session yet, the edge shows a Houseguest sign-in page. They confirm their email with a 6-digit code.
4. The edge checks each request. A request with a valid session for this preview passes. Anything else is refused: no session, a revoked viewer, an ended preview.
5. The agent forwards it. The request travels down the agent’s outbound connection. The agent checks the hostname against its own allow-list, connects to the app with TLS, verifies the app’s certificate as a browser on your network would, removes Houseguest’s own cookie, and passes the request on.
6. The app answers as usual. Its own login, roles and data are unchanged. Houseguest decides who may reach the app at all; the app still decides what they can do in it.

One sign-in across several hostnames

A preview’s hostnames must share a parent domain, such as app.lab.example.com and api.lab.example.com under lab.example.com. The viewer’s sign-in applies to that parent, so one code covers every hostname in the preview, and the app’s cookies, redirects and cross-origin calls behave as they do on your network.

Two ways to address the app

• Its own hostnames. Viewers use app.lab.example.com, the name the app already has. Public DNS for each shared name points at the edge; inside your network the same names keep resolving to the app. On the hosted service the domain is verified once with a DNS TXT record.
• Houseguest addresses (hosted service). Viewers use an address such as app.acme.houseguest.page. No DNS changes, and the internal names never appear in public DNS or certificate logs. Fits apps that use relative links.

Details: Domains and addresses.

What happens at the end

When a preview ends (its time runs out, or someone presses End), every request answers “This preview has ended”. The hostnames are free for a new preview at once. Revoking one person stops them at their next request. Open SSH and TCP connections run until they close: see TCP and SSH.