Allow-lists

An agent forwards only what its own host allows. Two settings, read at start, set that ceiling:

• HG_ALLOW: web hostnames.
• HG_ALLOW_TCP: TCP services such as SSH or a database.

A request for anything else is refused by the agent itself, whatever the edge asks. This is what keeps a shared app from becoming a shared network: even a compromised edge can reach only what these lists allow.

Web hostnames: HG_ALLOW

A comma-separated list. Each entry is one of:

Entry	Meaning
app.example.com	Forward this name to HG_UPSTREAM. Always on
legacy.example.com=10.0.0.9:8443	Forward this name to its own internal address. Always on
app.example.com=dns	Forward this name to the internal address the host’s DNS gives for it (=dns:8443 for another port). Always on
*.example.com	Any one name directly under example.com, sent to HG_UPSTREAM, once the console turns it on
*.example.com=10.0.0.5:443	The same, with its own internal address
*.example.com=dns	The same, each name to the address DNS gives for that name

Examples:

Goal	HG_ALLOW
Each name wherever internal DNS says (the console’s default)	app.example.com,api.example.com with HG_UPSTREAM=dns
A fixed set of names, all behind one reverse proxy	app.example.com,api.example.com with HG_UPSTREAM=10.0.0.5:443
One name somewhere else	app.example.com,legacy.example.com=10.0.0.9:8443
Let the console choose names under a domain	*.lab.example.com with HG_UPSTREAM=dns or HG_UPSTREAM=10.0.0.5:443

Rules:

• Wildcards cover exactly one label. *.lab.example.com allows docs.lab.example.com, not a.docs.lab.example.com and not lab.example.com itself. Add exact entries for anything else.
• A wildcard needs at least two labels after the star. *.com and *.example are refused as too broad.
• Every name needs an address, either its own (=address:port or =dns) or HG_UPSTREAM.
• dns uses internal answers only (10/8, 172.16/12, 192.168/16, 100.64/10, fc00::/7). A name that resolves to a public address, or to the Houseguest™ edge, is refused with a message saying so. See Addresses from internal DNS.
• The agent always connects to the app with TLS on that address, sends the real hostname, and checks the certificate against it.

Exact entries or a wildcard?

• Exact entries are the stricter choice: the agent forwards those names and nothing else, and changing them needs a change on the host.
• A wildcard lets people with the Turn hostnames on and off permission choose names in the console without touching the host. The trade-off: a compromised edge could reach any name under that wildcard behind the agent’s address, not only the names turned on. Your app’s own login still applies.

HG_REMOTE_HOSTS=off makes the agent ignore the console’s choices entirely, so only exact entries work.

Turning names on in the console

For an agent with a wildcard entry: Agents → agent → Turn on a hostname, one name per line, Turn on. The console sends the list to the agent over its own connection and the agent applies it at once, with no restart. Names outside the wildcard are ignored by the agent.

Turn off removes a console-chosen name. It is refused while the name is in an open preview: remove it from the preview, or end the preview, first. Exact HG_ALLOW entries show as Set on the host and change only on the host. Names whose address comes from DNS also say internal DNS, and the ceiling marks those entries (internal DNS).

Each name also needs public DNS pointing at the edge before it can be previewed on its own hostname. See Domains and addresses.

TCP services: HG_ALLOW_TCP

Exact entries only, comma-separated, each name:port=address:port:

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

• The name is what viewers type. It needs no public DNS and can be any name you choose (lowercase letters, digits, hyphens and dots).
• The address is where the agent connects inside your network.
• There are no wildcards, and the console cannot add to this list.
• An agent can serve only TCP services: leave HG_ALLOW empty. (The installer still asks for --upstream.)

After the agent restarts, Agents counts its TCP services and the agent’s page lists them. See TCP and SSH for adding them to a preview.

Changing a list

Both lists are read when the agent starts.

• Docker: docker rm -f houseguest-agent, then run the same docker run command with the new values and the same volume, without HG_JOIN.
• Docker Compose: edit compose.yaml and run docker compose up -d.
• No Docker: re-run the installer with every flag you want to keep (--upstream, --allow, --allow-tcp, --upstream-ca) and without --join. It rewrites its settings from the flags each time, so a flag left out is dropped.

The agent reports the new lists when it reconnects; the console shows them on the agent’s page under Set on the host.