Can I bind to a specific host? How is the host option passed through?

Yes, you can bind (or rather, check availability) against a specific host via the host option.

API surface

The host option is defined as part of Options in the type definitions:

"The host on which port resolution should be performed. Can be either an IPv4 or IPv6 address. By default, it checks availability on all local addresses defined in OS network interfaces. If this option is set, it will only check the given host." [index.d.ts:L36-L40]

How it flows through the code

1. In the main exported function, all options except reserve are spread into netOptions, which includes host if you passed it:

const {reserve, ...netOptions} = options ?? {};

[index.js:L119]

2. For each candidate port in the check sequence, getAvailablePort is called with {...netOptions, port} — so host rides along as part of the options object passed down [index.js:L138].

3. Inside getAvailablePort, if a host was explicitly provided (or port === 0), it skips iterating over all local network interfaces and just checks that single host directly:

const getAvailablePort = async (options, hosts) => {
	if (options.host || options.port === 0) {
		return checkAvailablePort(options);
	}
	...

[index.js:L61-L64]

If no host is given, it instead loops over all local hosts (from OS network interfaces) to verify the port is free on every interface before returning it [index.js:L61-L76].

4. checkAvailablePort ultimately does the real work — it creates a net.Server, calls server.listen(options, ...) (where options includes your host/port), and resolves with the bound port once available [index.js:L47-L60]. Node's net.Server.listen accepts a host in its options, so this is exactly where your host takes effect.

Test coverage confirming this behavior

• preferred port given IPv4 host binds to 0.0.0.0 explicitly and confirms the desired port is returned [test.js:L54-L62].
• port can be bound to IPv4 host when promise resolves gets a port with host: '0.0.0.0' and verifies a server can bind to it on that host [test.js:L44-L52].
• preferred ports is bound up with different hosts shows how binding a preferred port on one host (e.g., 127.0.0.1) doesn't block it being returned for a different host, since availability is host-scoped [test.js:L161-L177].
• There's also interaction with reserve: reserving a port blocks it globally by port number regardless of host, even though normal (non-reserved) locking is host-specific — see reserve option blocks the same port on other hosts too [test.js:L206-L212] and the doc note: "Reserved ports are locked globally by port number for the current process, even if you looked them up with a specific host or ipv6Only option." [index.d.ts:L18].

So in short: host is just forwarded straight through the options chain into net.Server.listen(), and its presence changes whether get-port checks a single host or all local interfaces.

FOLLOW_UPS:

• How does the ipv6Only option interact with host?
• What does clearLockedPorts() actually reset?
• How does portCheckSequence decide port order?