Share from your computer

houseguest share puts a port on your own computer (a dev server, a demo build) on a Houseguest™ address, for the people you name, for as long as you say. Nothing is installed: it is the same houseguest command viewers use for TCP and SSH.

houseguest share 3000 --invite [email protected] --for 2h

https://k7f2.acme.houseguest.page/  (invite sent · ends in 2h · Ctrl-C ends it now)
  This address alone does not open it. Viewers open the link in their invite email.
  Your link (works once): https://k7f2.acme.houseguest.page/__hg/accept?t=…
✓ 14:02 [email protected] signed in

Alice gets the usual invite email, signs in like for any preview, and sees what your computer serves on port 3000. Each time a viewer signs in or signs out, a line appears (✓ 14:02 … signed in, ← 14:31 … signed out). Ctrl-C ends it at once.

The first line is the preview’s address, not a link to send: an invite preview refuses anyone who opens the bare address with This preview needs an invite. Viewers open the link in their invite email.

Your link is a one-time invite for you, so you can check what viewers see. It is not emailed, works once, in one browser, and does not count toward the preview’s viewer limit. In the console it shows as Owner · own link. --no-link skips it. Standing access (--allow) prints none: there, the address is the link, and you sign in with an emailed code if you are on the list.

Before you start

Install the houseguest command. During early access, the download details come with your early-access invitation. On macOS and Linux:
Terminal window
```
curl -fsSL https://get.houseguest.dev/install.sh | sh
```
On Windows, in PowerShell:
Terminal window
```
irm https://get.houseguest.dev/install.ps1 | iex
```
The script downloads the build for your computer, checks it against the published SHA256SUMS, installs it to ~/.local/bin (on Windows, %LOCALAPPDATA%\Programs\Houseguest) and adds that folder to your PATH. No sudo or administrator rights. Open a new terminal afterwards. Running it again upgrades; sh -s -- --version 0.4.0 pins a version and sh -s -- --uninstall removes it. To install by hand instead, download the file for your computer, check it against SHA256SUMS, make it executable and move it onto your PATH. houseguest version prints its version.
You need the Create previews and Use Houseguest addresses permissions. Members have both; Billing, Auditor and No workspace role do not.
Your workspace’s admins can turn Terminal sharing off in Settings → Security. It is on by default.

The first houseguest share opens the console in your browser and prints the same address and a code:

Sign in to the console to share. Open:

  https://console.houseguest.dev/cli/approve

and enter the code:

  BCDF-2345

Sign in to the console as usual (including the second step, if your workspace requires one) and enter the code under Enter the code shown in your terminal. The page then shows what you are approving: the command, your computer’s name, when it was requested and the workspace. Press Approve sign-in. If the console asked you to sign in first, open the address again afterwards.

The address never contains the code, so a link someone sends you cannot sign their command line in as you. Only enter a code from a terminal you are using yourself. A code works once, for 10 minutes; after 10 codes that match nothing in an hour, the page refuses more for that hour.

houseguest 0.4.0 or later is needed. Older versions stop with Update houseguest to sign in and the install command; run it to upgrade.

The command line then stays signed in for 12 hours (never longer than your console session), as you, in that workspace. After that, the next houseguest share opens the browser again. If you belong to several workspaces, --workspace SHORTNAME picks one; otherwise it uses the workspace the console is in.

houseguest status lists the sign-in; houseguest logout --console ends it.

Who can open it

The options match the console’s New preview form:

Option	Access
`--invite EMAIL`	Invite: a single-use link emailed to each address. Repeat it, or separate addresses with commas
`--allow EMAIL` or `--allow @domain`	Standing access: the people listed sign in with an emailed code
`--code`	Invites also need a code sent to the address

Use one of --invite or --allow. Your workspace’s allowed viewer domains apply, as in the console. If email is not set up (self-hosted edges), invite links are printed once for you to send.

Options

Option	Default
`PORT`		The port on this computer. Also `localhost:PORT`, `127.0.0.1:PORT` or `[::1]:PORT`. A bare port reaches the app whether it listens on `127.0.0.1` or `::1`
`--path PREFIX=PORT`	None	Send requests under `PREFIX` to another port on this computer. Repeat it, up to 8. See Several local services
`--for DURATION`	2 hours	How long it stays open: `30m`, `2h`, `48h`. At most 8 hours on Free, 7 days on other plans
`--name NAME`	`local-<label>`	The preview’s name in the console
`--no-link`	Off: your link is printed	Print no one-time link for yourself (invites only)
`--workspace SHORTNAME`	The console’s current workspace	When you belong to several

Several local services

An app that runs as a front end on one port and an API on another can share both on one address with --path:

houseguest share 3000 --path /api=8080 --path /auth=9000 --invite [email protected]

https://k7f2.acme.houseguest.page/  (invite sent · ends in 2h · Ctrl-C ends it now)
  This address alone does not open it. Viewers open the link in their invite email.
  /api  → localhost:8080
  /auth → localhost:9000
  /     → localhost:3000 (everything else)

A path and everything below it go to its port: /api matches /api and /api/orders, not /apis or /api-docs.
The longest path wins: with --path /api=8080 --path /api/v2=8082, /api/v2/orders goes to 8082 and /api/users to 8080.
Everything else goes to the main port, here 3000.
The path is forwarded unchanged. The API on 8080 receives /api/orders, not /orders, so it must serve under its prefix (most frameworks have a base-path setting).
One address, one origin, one sign-in. The page calls /api/… on its own origin, so no CORS settings and no second sign-in. The viewer’s session covers every path.
WebSockets and streamed responses work on every path, as on the main port.
Each target is a port on this computer, on the same host as the main port: --path /api=8080, or --path /api=127.0.0.1:8080 when the main port is 127.0.0.1:3000. At most 8 paths; a path starts with /, cannot be / alone, and cannot be named twice.

The paths are fixed when the share starts. To change them, end the share and start a new one.

Apps on separate hostnames that share one sign-in (app. and api. of a domain) need the full agent instead.

--path needs houseguest 0.5.0 or later. If the edge does not support it yet, the command stops with this edge does not support –path before anything is shared.

How long it lasts

A share ends, and its preview closes, when any of these happens:

Ctrl-C in the terminal.
The end of --for.
Your computer goes away. When the connection drops (sleep, a network change), viewers see “The app is not reachable right now”. If it is back within 90 seconds, the share carries on. If not, Houseguest ends it. When the computer wakes later, houseguest share says the share ended and exits.
Someone ends the preview in the console, or ends the share on the Agents page.

Nothing is left behind: the preview ends, and the micro agent and its address are removed.

A share is never permanent. Extending its preview in the console is limited to the plan’s longest share, counted from its start.

What it can reach

houseguest share runs a micro agent: a small agent for this one share, inside the houseguest command. It differs from an agent installed in your network:

It forwards only to the ports named in the command, on this computer (127.0.0.1 or ::1): the main port and each --path. The command refuses any other address before it connects. The Houseguest edge stores the ports when the share starts and refuses a micro agent that reports any other target or path. The edge picks each request’s port from what it stored, and the micro agent dials only ports from its own command line.
It serves only its own preview. It cannot be added to other previews or carry TCP services.
Your app sees requests as if they came from a local browser: Host: localhost:PORT, and an Origin of http://localhost:PORT where the browser sent one. X-Forwarded-Host carries the share’s address. Redirects to http://localhost:PORT are sent back as the share’s address.
WebSockets work, so dev servers’ hot reload (Vite, Next.js) keeps working for viewers.
As with any Houseguest address, links your app writes with an absolute localhost URL in the page itself point at the viewer’s own computer. Relative links work.

Plain HTTP is fine here: the connection from the micro agent to your app stays on your computer.

Good to know

Each share gets a new random address, such as k7f2.acme.houseguest.page. Addresses cannot be chosen or kept from one share to the next.
The first share in a new workspace can take 1 to 2.5 minutes to answer while the workspace’s certificate is issued. Later shares answer at once.
Sign-outs are reported, tab closes are not. A viewer who closes the tab without signing out produces no signed out line.

In the console

Previews lists the share like any preview, labelled Local · your computer’s name. Invite more people, revoke, or end it there.
The preview’s Hostnames tab lists the Ports on your computer’s name: each path and its port, then everything else and the main port.
Agents → Terminal shares lists the micro agents running now (and those that ended today), who started each, its preview and ports, and End.
Insights shows the time each person’s terminal shares ran in the selected range (Insights needs View previews across the workspace, so Members do not see it).
The Activity log records each start (with its paths) and end, and every refusal (limit reached, terminal sharing off, a missing permission, an address that is not on this computer).

Limits

	Free	Pro	Business	Early access
Terminal shares running at once, per person	1	2	5	5
Longest share	8 hours	7 days	7 days	7 days

Each share also counts as an open preview under the workspace’s open-preview limit. Terminal sharing needs Houseguest addresses, so it is a feature of the hosted service: a self-hosted edge does not offer it.