TCP and SSH

To share an app running on your own computer instead, see Share from your computer.

A preview can include TCP services as well as web hostnames: SSH, Postgres, Redis, RDP and so on. Viewers reach them over the edge’s port 443, with the same sign-in as the preview. There are two ways to connect:

	Command line (`houseguest`)	Browser terminal
For	Any TCP service	SSH
Viewer installs	One `houseguest` binary	Nothing
Encryption to the server	The edge relays bytes only: SSH and other encrypted protocols stay encrypted end to end; an unencrypted protocol is readable at the edge	The edge runs the SSH session and sees it in the clear, as it sees web previews
Sign-in	Once per preview: `houseguest login`, approved in the browser	The preview’s browser sign-in

1. Allow the service on the agent

TCP services are listed on the agent’s host, as exact entries only:

-e HG_ALLOW_TCP='ssh.lab.example.com:22=10.0.0.10:22,db.lab.example.com:5432=10.0.0.20:5432'

Each entry is name:port=internal-address:port. The name is what viewers type; it needs no public DNS. The console cannot add to this list. Restart the agent after changing it. Details: Allow-lists.

2. Add it to a preview

On the preview’s page, TCP & SSH → Add TCP service, and choose from the services your agents report. This needs the Add TCP services permission on the preview. The page then shows the commands viewers run.

Remove refuses new connections at once. Connections already open end when they close.

For viewers

Command line

Install houseguest with curl -fsSL https://get.houseguest.dev/install.sh | sh on macOS and Linux, or irm https://get.houseguest.dev/install.ps1 | iex in PowerShell on Windows. The script checks the download against the published SHA256SUMS and puts the command on your PATH; see Share from your computer for the details. During early access, the person who shared the preview passes on the download details, which come with their workspace’s early-access invitation. Then sign in once per preview, using the preview’s address:

houseguest login app.lab.example.com

It prints an address and a code, and opens the address in your browser:

Sign in through a browser where you can open the preview. Open:

  https://app.lab.example.com/__hg/cli

and enter the code:

  BCDF-2345

In the browser where you opened the preview (sign in there first if needed), enter the code. The page shows what you are approving: the command, the preview, your computer’s name and when it was requested. Press Approve sign-in. Only approve a sign-in you started yourself, just now: anyone who gets you to enter their code gets your access.

SSH, with your own keys and known_hosts as usual:

ssh -o ProxyCommand='houseguest connect %h:%p' user@ssh.lab.example.com

or permanently, in ~/.ssh/config:

Host *.lab.example.com
    ProxyCommand houseguest connect %h:%p

Anything else, through a local port:

houseguest forward 15432 db.lab.example.com:5432
psql -h 127.0.0.1 -p 15432 -U app

Command	Does
`houseguest login HOST`	Signs in to the preview at `HOST`. Saved per preview domain
`houseguest connect NAME:PORT`	Connects standard input and output to the service (for `ProxyCommand`)
`houseguest forward [ADDR:]PORT NAME:PORT`	Listens on a local port (default `127.0.0.1`) and forwards each connection
`houseguest status`	Lists sign-ins and when they end
`houseguest logout [HOST\|--all]`	Ends a sign-in

--via HOST picks the sign-in to use when you have several. Where your local DNS answers for the preview’s name itself, add --edge-ip <edge address> to login; it is remembered.

The sign-in is stored in ~/.config/houseguest/tokens.json (macOS: ~/Library/Application Support/houseguest, Windows: %AppData%\houseguest), readable only by you. It ends when the preview ends, when you are revoked, or with houseguest logout.

Browser terminal

For SSH services, the preview’s page links open the browser terminal: https://<preview address>/__hg/ssh?target=ssh.lab.example.com:22. Enter the username and a password or a private key. They go to the server for that session only and are never stored or logged.

The server’s host key is trusted on first use and remembered for your workspace. If it changes, the terminal stops and shows the old and new fingerprints, and connects only after I checked it: trust the new key. Check the fingerprint with the server’s owner first: the new key then applies to every viewer of that service in the workspace.
A session closes after 30 minutes without activity.

What the request log shows

TCP connections, SSH sessions and terminal sessions appear in the preview’s Requests with the service and port, and command-line sign-ins as sign-in steps. Their content is never recorded.

Good to know

Connections are checked when they start. Revoking a person, removing the service or ending the preview stops new connections; open ones run until they close (the terminal closes after 30 minutes idle).
A workspace’s plan decides whether TCP services and the browser terminal are available: Early access, Pro and Business include them; Free does not.