Fix programs that cannot resolve *.localhost
Use this guide when a lane hostname opens in your browser but another program fails to find it, often with ENOTFOUND or “no such host”.
::example{slug="frameworks-wrangler-workers"}
Check your system
Section titled “Check your system”Chrome, Edge and Firefox answer names under localhost themselves, but other programs ask the operating system, and some, such as workerd behind wrangler dev, musl binaries and Go programs built without cgo, ask DNS directly. The doctor’s hosts group says whether your system resolves the names:
$ devlanes doctorWrite the hostnames to the hosts file
Section titled “Write the hostnames to the hosts file”On macOS and Linux devlanes keeps the exact hostnames of your lanes in the hosts file when your system does not resolve them. A project that runs one of the programs above turns it on for itself:
lanes: hosts_file: alwayslanesWhich worktrees get a lane, how many ports each lane reserves, and values computed per lane (lane.<name>).
lanes.hosts_fileWhether this project's hostnames are also written to /etc/hosts, for programs that cannot resolve *.localhost by themselves (Wrangler's workerd, musl or pure-Go binaries). Overrides the user's hostnames.hosts_file (default auto), except that a user never always wins. Writing needs the helper devlanes setup installs, and only exact names are written, never wildcards.
devlanes writes the file through a small helper. Start a lane of the project, then run the setup command, which installs the helper and asks for your password once:
$ devlanes start$ devlanes setupA hosts file holds exact names only, so wildcard hostnames need the resolver below. hostnames.hosts_file set to never in your user config turns the file off. devlanes does not write the hosts file on Windows; Windows 11 resolves the names itself.
Use a top-level domain of your own
Section titled “Use a top-level domain of your own”The resolver strategy covers every name, wildcards included. Lane domains then end in a domain you choose, such as myapp1.test, and the daemon answers them. The domain has to be test, internal or home.arpa, or a name under one of them.
hostnames: resolver: resolver tld: testhostnamesHow lane hostnames such as api.acme2.localhost resolve to this machine: the strategy (resolver), its tld, and whether names also go into /etc/hosts (hosts_file). The defaults need no setup for browsers that resolve *.localhost.
hostnames.resolverWhich domain lanes get and what makes their hostnames resolve; defaults to localhost. resolver also needs tld and a one-time devlanes setup; public is not supported yet.
hostnames.tldTop-level domain for the resolver strategy, such as test; required there. It must be test, internal, home.arpa or a domain under one of them (or under localhost), made of valid DNS labels, because any other name could belong to a real site; the file is rejected otherwise, whatever the strategy. A new devlanes CA may sign names under the tld set when it is created, whatever the strategy, so switching to another tld later needs a new CA.
Then let the system send that domain to the daemon, which asks for your password or an administrator’s approval, and restart the daemon so lanes take the new domain:
$ devlanes setup$ devlanes daemon restartOn Linux this needs systemd-resolved from systemd 258 or later.
If you stop using the resolver
Section titled “If you stop using the resolver”Take the resolver out while keeping the CA trusted, remove the two settings, and restart the daemon. Run devlanes setup again afterwards if a project still needs the hosts file.
$ devlanes setup --remove --keep-ca$ devlanes config unset hostnames.resolver$ devlanes config unset hostnames.tld$ devlanes daemon restartIf the program runs in a container
Section titled “If the program runs in a container”A container resolves names on its own, and devlanes has no step that connects it to a lane by hostname.