Skip to content
HomeGitHub

.nearhostrc

A .nearhostrc is a YAML file in a project’s root directory. You commit it with the project, so everyone who adds the project gets the same ports, hosts and main name, and each worktree can fill them from its own .env.

The file only ever proposes. A host or main name that is not .test, a wildcard, localhost, a new loopback port and Docker access all wait for your approval before they go live. See Approval.

version: 1
alias: ${APP_HOST:-app.local.example.com}
routes:
- port: ${APP_PORT:-8000}
label: app
hosts:
- api.local.example.com
- '*.status.local.example.com'
- port: ${FORWARD_REVERB_PORT:-8080}
label: reverb
hosts: [ws.local.example.com]
- port: ${FORWARD_MINIO_PORT:-9000}
label: minio
hosts: [files.local.example.com]
- port: ${VITE_PORT:-5173}
role: ignore
label: vite
docker_clients: true

With this .env beside it, the app is served at https://app.local.example.com and https://api.local.example.com from port 8010. A name one label under status.local.example.com, such as eu.status.local.example.com, reaches the same port; the hosts file cannot hold a pattern, so its names need DNS that points them at this machine. Reverb is served at ws.local.example.com from port 8090, and MinIO at files.local.example.com from port 9010:

APP_PORT=8010
FORWARD_REVERB_PORT=8090
FORWARD_MINIO_PORT=9010
Key Type Meaning
version integer Required. Must be 1.
alias string Optional. The project’s main name: <name>.test, or any one domain.
routes[].port integer Required. The port on the server. A number from 1 to 65535, or a variable that gives one.
routes[].role string Optional. web, loopback or ignore. web when left out.
routes[].label string Optional. A description, shown with the route.
routes[].hosts list Optional, web routes only. Names to serve the route at: exact names or wildcard patterns.
docker_clients boolean Optional. true serves the project to Docker containers on this machine too. See Docker clients.

The roles mean what they mean in config.yaml. See Routes and roles.

The file is the authority on the routes it lists. Their hosts replace any that presets found for those ports. A port the project has that the file does not list stays visible, but a web one becomes ignore, so only the file says what is served.

nearhost add --alias wins over alias:, and alias: wins over <name>.test. Removing alias: from the file leaves the current main name as it is.

  • A file that lists routes needs at least one web route among them.
  • The first web route is served at the project’s main name. Every later web route needs at least one host.
  • A port, or a host, listed twice is an error.
  • Only web routes have hosts.
  • The main name may be listed as a host only on the first web route, where it is served anyway.
  • docker_clients works only for a project on this machine, not one on a server.
  • Hosts and the main name must be lowercase. The main name cannot be a wildcard pattern, localhost, nearhost.localhost or an IP address. No host can be nearhost.localhost.

${VAR} and ${VAR:-default} work in ports, hosts, labels, roles and the alias. They are filled from .env.local, then .env, in the project’s directory, so a value in .env.local wins. They are never filled from Nearhost’s own environment.

A variable with no value and no default is an error that names it:

.nearhostrc: ${APP_PORT} has no value in .env.local or .env, and no default

A variable can fill part of a value, as in app.${APP_DOMAIN}. Worktrees of one repository can then share the committed file and each serve its own hosts. Approval works on the filled values, so you approve the names that will actually be served, and a change in .env that gives a new real domain asks again.

Every error in the file itself starts with .nearhostrc. nearhost add stops with it, and the interface and nearhost doctor show it with the project.

A key this version of Nearhost does not know is an error, rather than being ignored:

.nearhostrc: line 4: key "hostz" is not understood by this version of Nearhost; update Nearhost, or remove it

So is a version newer than this Nearhost understands:

.nearhostrc is version 2; this Nearhost understands version 1, so update Nearhost

Run nearhost update for the second. For the first, check the key’s spelling against Keys.

These need your approval before they go live:

  • a host that does not end in .test;
  • a wildcard pattern, even one under .test;
  • localhost;
  • a main name that does not end in .test;
  • a loopback port that the approved project did not forward as loopback, since Nearhost binds that port on localhost on this machine;
  • docker_clients: true.

A .test host, a web port, a label or another role needs none. Neither does a host the project already serves, a new label on a loopback port you approved, or a loopback port that a preset such as Vite’s proposes. A loopback port is shown for approval as localhost:5173 (binds localhost:5173 on this machine), after the hosts.

Each front end asks in its own way:

  • The interface. When you add a project, the last step lists what needs approval, and enter approves it and saves. When a project’s file changes later, the project shows .nearhostrc asks for 1 change that needs approval · a to review. Press a to see what it asks for, then y to approve, n to decline or esc to leave it for later. A declined change is not asked about again until the file changes or Nearhost restarts.

  • nearhost add. At a terminal it first says what approving a name does, then asks about each item on its own, as <item>: approve? [y/N]. A no drops that host, loopback port or docker_clients, and the add goes on without it. A refused main name falls back to the .test one, and the summary names what was left out. Nearhost asks about a refused item again when it next reviews the project. A host typed with --host, or a main name typed with --alias, is approved by typing it. Without a terminal it adds nothing, and names the items. For the file at the top of this page:

    nearhost: not added: this project asks for things that need your approval (*.status.local.example.com, api.local.example.com, ws.local.example.com, files.local.example.com, app.local.example.com, docker_clients); run nearhost add in a terminal, or open nearhost
  • nearhost up. It cannot approve anything. A project whose file asks for something new keeps serving what was approved before, and its log says what is waiting. Open nearhost to approve it.

Nothing approves itself.

Nearhost reads the file, and applies what it finds:

  • when a project starts;
  • when you press r on a project in the interface;
  • when an agent asks Nearhost to read it again, or runs the doctor on the project.

A change that needs no approval, such as a port moved in .env, a new label or a new .test host, applies at once and is saved to config.yaml. A change that needs approval waits, and the routes approved before keep serving until you approve it. If the file has an error, or is deleted after it was approved, the project keeps serving what was approved and shows the problem.

nearhost doctor on the command line reads the file too, but only reports. It applies and saves nothing. It reports a file with an error, a change that waits for approval, and a change that needs none but has not been applied yet.

Nearhost answers only this machine. On Linux, a request from a container comes from a Docker network, not from this machine’s loopback address, so Nearhost drops it. docker_clients: true also serves the project to the networks Docker has on this machine, while other projects stay loopback-only. It works only for a project on this machine, and it always needs your approval. Docker Desktop on macOS already delivers container requests from 127.0.0.1, so this matters on Linux.

A container also needs to find the host and trust the local certificate authority. See Callbacks from Docker containers to a local HTTPS domain.

To set only the main name, and leave the routes to discovery and to you, give the file version and alias:

version: 1
alias: ${APP_HOST:-app.local.example.com}

The routes stay as discovery found them or as you set them. The file removes only the hosts that an earlier, approved version of it gave, and the main name from any route other than the first web route. A later web route left with no hosts once the main name is removed becomes ignore.