.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: 1alias: ${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: vitedocker_clients: trueWith 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=8010FORWARD_REVERB_PORT=8090FORWARD_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
webroute 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_clientsworks 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.localhostor an IP address. No host can benearhost.localhost.
Variables
Section titled “Variables”${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 defaultA 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.
Errors
Section titled “Errors”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 itSo is a version newer than this Nearhost understands:
.nearhostrc is version 2; this Nearhost understands version 1, so update NearhostRun nearhost update for the second. For the first, check the key’s spelling against Keys.
Approval
Section titled “Approval”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
loopbackport that the approved project did not forward as loopback, since Nearhost binds that port onlocalhoston 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
enterapproves it and saves. When a project’s file changes later, the project shows.nearhostrc asks for 1 change that needs approval · a to review. Pressato see what it asks for, thenyto approve,nto decline orescto 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 ordocker_clients, and the add goes on without it. A refused main name falls back to the.testone, 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. Opennearhostto approve it.
Nothing approves itself.
When it is read
Section titled “When it is read”Nearhost reads the file, and applies what it finds:
- when a project starts;
- when you press
ron 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.
Docker clients
Section titled “Docker clients”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.
A file without routes
Section titled “A file without routes”To set only the main name, and leave the routes to discovery and to you, give the file version and alias:
version: 1alias: ${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.