---
title: "hostnames in config.yaml"
url: https://devlanes.run/docs/reference/config/user/hostnames/
description: "Reference for the hostnames key in ~/.devlanes/config.yaml."
---

# hostnames in config.yaml

A top-level key of [`~/.devlanes/config.yaml`](/docs/reference/config/user/).

## `hostnames`

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

```yaml devlanes-user
hostnames:
  hosts_file: auto
  resolver: localhost
```

### `hostnames.base_domain`

Type: string.

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

```yaml devlanes-user
hostnames:
  base_domain: dev.example.invalid
```

### `hostnames.dns_provider`

Type: mapping.

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

```yaml devlanes-user
hostnames:
  dns_provider:
    cloudflare:
      token: ${{ env.CF_API_TOKEN }}
```

### `hostnames.dns_provider.cloudflare`

Type: mapping. Required.

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

```yaml devlanes-user
hostnames:
  dns_provider:
    cloudflare:
      token: ${{ env.CF_API_TOKEN }}
```

### `hostnames.dns_provider.cloudflare.token`

Type: string or an [expression](/docs/reference/expressions/). 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.

```yaml devlanes-user
hostnames:
  dns_provider:
    cloudflare:
      token: ${{ env.CF_API_TOKEN }}
```

### `hostnames.hosts_file`

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.

```yaml devlanes-user
hostnames:
  hosts_file: auto
```

### `hostnames.resolver`

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.

```yaml devlanes-user
hostnames:
  resolver: localhost
```

### `hostnames.tld`

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.

```yaml devlanes-user
hostnames:
  tld: test
```
