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

Yes — the host option is supported. Here's how it flows through the code:

API definition: The Options type includes an optional host field: a string that should be either an IPv4 or IPv6 address. By default (when omitted), get-port checks availability on all local addresses discovered via OS network interfaces; if you set host, it restricts the check to just that address [index.d.ts:L3-L40].

Runtime logic: In getAvailablePort, the host option determines the code path:

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

	for (const host of hosts) {
		try {
			await checkAvailablePort({port: options.port, host});
		} catch (error) {
			if (!['EADDRNOTAVAIL', 'EINVAL'].includes(error.code)) {
				throw error;
			}
		}
	}

	return options.port;
};

[index.js:L61-L76]

• If you explicitly pass options.host (or if port: 0 is requested, meaning "any random port"), it skips the multi-host loop entirely and calls checkAvailablePort(options) directly with just that single host/port combination.
• If no host is given, it instead iterates over hosts — the set of local addresses gathered by getLocalHosts() — checking your preferred port against each one in turn, so the port is confirmed free across all interfaces before being returned.

Underlying check: checkAvailablePort does the actual work — it creates a net.createServer(), calls server.listen(options, ...) with whatever {port, host} (or other ListenOptions) was passed, and resolves with the bound port once listening succeeds, immediately closing the server afterward [index.js:L47-L60].

Host discovery: When no explicit host is set, getLocalHosts() builds the candidate host list by reading os.networkInterfaces(), plus it always includes undefined (to let net.createServer pick its own default) and '0.0.0.0' (default IPv4 bind-all) as fallbacks [index.js:L31-L45].

Test coverage confirms this behavior: for example, preferred port given IPv4 host binds against host: '0.0.0.0' and expects the desired port back [test.js:L54-L62], and port can be bound to IPv4 host when promise resolves verifies the resolved port can actually be bound on '0.0.0.0' [test.js:L44-L52]. There's also a test showing that when a port is bound on different hosts (default, 0.0.0.0, 127.0.0.1), get-port correctly skips all of them and returns the next free one, since without an explicit host it checks across the local host set [test.js:L167-L176].

Note also that the Options type extends Omit<ListenOptions, 'port'> [index.d.ts:L3-L40], so other Node.js net.ListenOptions properties (like ipv6Only) can be passed alongside host too — this interacts with host resolution, as seen in tests around ipv6Only behavior [test.js:L219-L235].

FOLLOW_UPS:

• How does the ipv6Only option affect host checks?
• What does clearLockedPorts() do internally?
• How does the reserve option lock ports globally?