---
title: "Wildcard tenants"
url: https://devlanes.run/examples/web-wildcard-tenants/
description: "Serve every tenant on its own subdomain with a wildcard host, while exact hostnames and a fallback gateway take the rest."
---

# Wildcard tenants

A small multi-tenant product as four Hono services in one npm workspace. Each tenant gets a subdomain through a wildcard hostname, a gateway catches every other subdomain of the lane, and the exact hostnames `app.` and `go.` win over both.

## Requirements

- devlanes, with `devlanes setup` run once
- Node 22 or later

## Run it

```sh
cd web-wildcard-tenants
devlanes start
```

`devlanes start --no-ui` prints the start as text:

```text
example-wildcard-tenants@0 (main): 4/4 ready
ready app http://127.0.0.1:20540 https://app.example-wildcard-tenants.localhost
ready sites http://127.0.0.1:20543
ready gateway http://127.0.0.1:20541
ready links http://127.0.0.1:20542 https://go.example-wildcard-tenants.localhost
```

Open https://app.example-wildcard-tenants.localhost. The page says `This is lane 0 of example-wildcard-tenants.`, sets a session cookie and links to the tenant pages, the short links and a subdomain no service claims.

## During a start

1. The first start of a lane runs the `install` task (`npm install` at the example root), which installs every workspace under `apps/` and `packages/`.
2. devlanes computes the lane var `sites_domain` from `domain('example-wildcard-sites')`: `example-wildcard-sites.localhost` in lane 0, `example-wildcard-sites1.localhost` in lane 1.
3. It starts the four services with `run_script`, each from its own `apps/<service>/package.json`, and waits for `/healthz` on each.
4. The proxy routes the hostnames:

| Hostname                                 | Service   | Route                          |
| ---------------------------------------- | --------- | ------------------------------ |
| <code>app.<wbr>example-wildcard-tenants.<wbr>localhost</code> | `app`     | exact                          |
| <code>go.<wbr>example-wildcard-tenants.<wbr>localhost</code>  | `links`   | exact                          |
| <code>*.<wbr>example-wildcard-sites.<wbr>localhost</code>     | `sites`   | wildcard                       |
| <code>*.<wbr>example-wildcard-tenants.<wbr>localhost</code>   | `gateway` | wildcard with `fallback: true` |

`app` sets `session=...; Domain=example-wildcard-tenants.localhost`, so the browser sends the cookie to every name under the lane domain, `go.` and the gateway's subdomains included. Tenant pages sit under `example-wildcard-sites.localhost`, which is another site, and never get it. `sites` reads the tenant from the `Host` header, `gateway` names the subdomain it got, and `links` redirects `/hello` and `/sale` to alice's and bob's pages. Every service also answers `/request`, which returns the service, the hostname it got and the `Cookie` header.

## Resolving wildcard names

Windows 11, macOS 26 and Linux with systemd-resolved answer every `*.localhost` name with loopback, wildcards included, and Chrome, Edge and Firefox do so on any OS. Older macOS, Windows Server and programs that do their own DNS (workerd, musl or pure-Go binaries, containers) do not. The hosts file cannot hold wildcards, so those programs reach `*.example-wildcard-sites.localhost` only through the resolver strategy described in the HTTPS guide.

## Try next

On Windows, add `--ssl-revoke-best-effort` to every `curl` command below.

- Ask each hostname which service answered. Exact names win and the fallback takes any other depth below the lane domain:

  ```sh
  curl -fsS https://app.example-wildcard-tenants.localhost/request
  curl -fsS https://go.example-wildcard-tenants.localhost/request
  curl -fsS https://billing.example-wildcard-tenants.localhost/request
  curl -fsS https://a.b.example-wildcard-tenants.localhost/request
  ```

  ```text
  {"service":"app","host":"app.example-wildcard-tenants.localhost","cookie":null}
  {"service":"links","host":"go.example-wildcard-tenants.localhost","cookie":null}
  {"service":"gateway","host":"billing.example-wildcard-tenants.localhost","cookie":null}
  {"service":"gateway","host":"a.b.example-wildcard-tenants.localhost","cookie":null}
  ```

- Take the app's cookie to the gateway and to a tenant. curl's cookie jar applies `Domain` the way a browser does:

  ```sh
  curl -fsS -c jar.txt -o /dev/null https://app.example-wildcard-tenants.localhost/
  curl -fsS -b jar.txt https://billing.example-wildcard-tenants.localhost/request
  curl -fsS -b jar.txt https://alice.example-wildcard-sites.localhost/request
  rm jar.txt
  ```

  ```text
  {"service":"gateway","host":"billing.example-wildcard-tenants.localhost","cookie":"session=bada74b0b665"}
  {"service":"sites","host":"alice.example-wildcard-sites.localhost","cookie":null}
  ```

  In a browser, open the app, then a tenant link and the `billing.` link: the tenant page says the session was not sent, the gateway page shows it.

- Follow a short link: `curl -sS -o /dev/null -w '%{http_code} %{redirect_url}\n' https://go.example-wildcard-tenants.localhost/sale` prints `302 https://bob.example-wildcard-sites.localhost/sale`.

- Request the bare sites domain. A wildcard does not cover its parent, so no route has the name and the TLS handshake fails: `curl -sS https://example-wildcard-sites.localhost/` prints `curl: (35) schannel: next InitializeSecurityContext failed: SEC_E_LOGON_DENIED (0x8009030c) - The logon attempt failed` on Windows.

- `devlanes stop links`, then open https://go.example-wildcard-tenants.localhost/hello. The proxy answers `503` with `DL201 Service not running` instead of handing the name to the gateway, because `go.` is still an exact route. `devlanes start links` brings it back.

- Check that the system resolver handles wildcard names without hosts-file entries: `node -e "require('node:dns').lookup('alice.example-wildcard-sites.localhost', { all: true }, (err, addrs) => console.log(err ?? addrs))"` prints `[ { address: '::1', family: 6 }, { address: '127.0.0.1', family: 4 } ]` on Windows 11.

- Start a second lane: `git worktree add ../examples-checkout -b feat/checkout`, then `cd ../examples-checkout/web-wildcard-tenants && devlanes start`. `devlanes lane new --name example-wildcard-tenants-review --start` in this folder gives the same lane 1 without a worktree. `devlanes url ls` then lists both lanes' routes, next to those of your other projects:

  ```text
  ready app.example-wildcard-tenants.localhost -> example-wildcard-tenants@0:app port=20540
  ready *.example-wildcard-sites.localhost -> example-wildcard-tenants@0:sites port=20543
  ready *.example-wildcard-tenants.localhost -> example-wildcard-tenants@0:gateway port=20541 fallback
  ready go.example-wildcard-tenants.localhost -> example-wildcard-tenants@0:links port=20542
  ready app.example-wildcard-tenants1.localhost -> example-wildcard-tenants@1:app port=20530
  ready *.example-wildcard-sites1.localhost -> example-wildcard-tenants@1:sites port=20533
  ready *.example-wildcard-tenants1.localhost -> example-wildcard-tenants@1:gateway port=20531 fallback
  ready go.example-wildcard-tenants1.localhost -> example-wildcard-tenants@1:links port=20532
  ```

  https://app.example-wildcard-tenants1.localhost says `This is lane 1 of example-wildcard-tenants.`, its tenants live under `example-wildcard-sites1.localhost`, and its session cookie never reaches lane 0.

- `devlanes lane clean 0 --yes` stops lane 0 and deletes its data and logs. Run it with `1` for the second lane.

## Files

- [`devlanes.yaml`](https://github.com/devlanes-run/examples/blob/d2a99f076179db99581cef85453a58b788f3970b/web-wildcard-tenants/devlanes.yaml): the `sites_domain` lane var, the `install` task and the four services with their hostnames.
- [`apps/app/src/session.ts`](https://github.com/devlanes-run/examples/blob/d2a99f076179db99581cef85453a58b788f3970b/web-wildcard-tenants/apps/app/src/session.ts): sets the session cookie on the lane domain.
- [`apps/sites/src/app.tsx`](https://github.com/devlanes-run/examples/blob/d2a99f076179db99581cef85453a58b788f3970b/web-wildcard-tenants/apps/sites/src/app.tsx): reads the tenant from `Host`; `views/TenantPage.tsx` shows which cookies arrived.
- [`apps/gateway/`](https://github.com/devlanes-run/examples/blob/d2a99f076179db99581cef85453a58b788f3970b/web-wildcard-tenants/apps/gateway) and [`apps/links/`](https://github.com/devlanes-run/examples/blob/d2a99f076179db99581cef85453a58b788f3970b/web-wildcard-tenants/apps/links): the catch-all page and the short-link redirects.
- [`packages/shared/`](https://github.com/devlanes-run/examples/blob/d2a99f076179db99581cef85453a58b788f3970b/web-wildcard-tenants/packages/shared): the environment parsing, the lane values and the `/healthz`, `/lane` and `/request` routes the services share.

## Docs

- [Wildcard hostnames](/docs/guides/services/#wildcard-hostnames)
- [A site of its own](/docs/guides/https/#a-site-of-its-own)
- [Programs that cannot resolve *.localhost](/docs/guides/https/#programs-that-cannot-resolve-localhost)
- [Hostnames on Windows](/docs/guides/windows/#hostnames)
- [Run and run_script](/docs/guides/run-scripts/)
- [`services.<name>.hosts` in the config reference](/docs/reference/config/)
