Skip to content

devlanes is in beta and not ready for production use.Report an issue

hostnames in config.yaml

A top-level key of ~/.devlanes/config.yaml.

Type: mapping.

How 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.

~/.devlanes/config.yaml
hostnames:
hosts_file: auto
resolver: localhost

Type: string.

Reserved for the planned public resolver; any value is rejected for now.

~/.devlanes/config.yaml
hostnames:
base_domain: dev.example.invalid

Type: mapping.

Reserved for the planned public resolver’s DNS-01 certificates; any value is rejected for now.

~/.devlanes/config.yaml
hostnames:
dns_provider:
cloudflare:
token: ${{ env.CF_API_TOKEN }}

Type: mapping. Required.

Reserved: Cloudflare credentials for DNS-01 certificates; not supported yet.

~/.devlanes/config.yaml
hostnames:
dns_provider:
cloudflare:
token: ${{ env.CF_API_TOKEN }}

Type: string or an expression. Required.

Reserved: Cloudflare API token allowed to edit the domain’s DNS records. Write an environment expression such as ${{ env.CF_API_TOKEN }}, not the token itself.

~/.devlanes/config.yaml
hostnames:
dns_provider:
cloudflare:
token: ${{ env.CF_API_TOKEN }}

Type: string.

Whether lane hostnames are also written to /etc/hosts, for programs that do not resolve *.localhost themselves (workerd, musl or pure-Go binaries); defaults to auto, which writes them only when a probe at daemon start shows the system resolver fails *.localhost. never here wins over every project; otherwise a project’s lanes.hosts_file replaces this value for that project. Writing needs the helper devlanes setup installs, only exact names are written (no wildcards), and resolver: hosts_file ignores this key.

Values:

  • auto: Write the exact hostnames only when the daemon’s startup check finds that the system resolver does not answer *.localhost with a loopback address.
  • never: Never write hostnames to /etc/hosts. Set in the user config, it applies to every project whatever the project sets.
  • always: Always write the exact hostnames, even when the system resolver handles *.localhost, for programs that send *.localhost to DNS themselves.
~/.devlanes/config.yaml
hostnames:
hosts_file: auto

Type: string. Default: localhost.

Which 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.

Values:

  • localhost: Lane domains end in .localhost (acme.localhost, acme2.localhost), which browsers and many system resolvers send to loopback by themselves. hosts_file covers programs that do not.
  • hosts_file: Keep .localhost names and always write exact hostnames to /etc/hosts, as hosts_file: always does, whatever hosts_file says; a project’s lanes.hosts_file still takes precedence. Needs the helper devlanes setup installs.
  • resolver: Lane domains become <project>.<tld> and <project><N>.<tld>, and so do the names domain() returns. They are answered by a DNS server the daemon runs on 127.0.0.1:15353, so wildcard hostnames resolve too for programs that use the system resolver. Needs tld and a one-time devlanes setup. Projects that set lanes.vars.domain or lanes.matrix keep their own domains, and domain() gives them .localhost names.
  • public: Reserved for public DNS names with DNS-01 certificates; not supported yet, so the config is rejected.
~/.devlanes/config.yaml
hostnames:
resolver: localhost

Type: string.

Top-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.

~/.devlanes/config.yaml
hostnames:
tld: test