What Nearhost changes on your machine
Nearhost asks for your password, trusts a certificate authority and edits /etc/hosts, so you should know exactly what it does. This page lists all of it, on your laptop and on your servers, and how to undo each part. The other concept pages explain the reasons; this one is the inventory.
Files on your laptop
Section titled “Files on your laptop”| Path | What it holds |
|---|---|
~/.config/nearhost/ (macOS, Linux)%APPDATA%\nearhost\ (Windows) |
config.yaml with your servers and projects, a lock file, an install id, presets you enabled, cached registry indexes, and run/ with SSH sockets |
~/Library/Application Support/nearhost/caddy (macOS)~/.local/share/nearhost/caddy (Linux)%LOCALAPPDATA%\nearhost\caddy (Windows) |
The local certificate authority, its private key and the certificates it signed, readable only by you. Beside caddy, page-secret holds the value of the cookie that lets your browser see the document list on Nearhost’s page, also readable only by you |
~/.cache/nearhost/update.json (macOS, Linux)%LOCALAPPDATA%\nearhost\cache\update.json (Windows) |
When Nearhost last checked for a new release |
~/.nearhost/ |
The socket coding agents on this machine use, readable only by you |
An absolute XDG_CONFIG_HOME, XDG_DATA_HOME or XDG_CACHE_HOME moves the first three. The install id is six random characters plus a hash of the machine id. It never leaves your machine.
Nearhost writes no log files. Its log is shown in the interface, or printed by nearhost up. Nearhost writes nothing to your projects unless you run nearhost export, which writes a .nearhostrc. A coding agent edits files itself, not through Nearhost.
What runs as root
Section titled “What runs as root”Nearhost never runs as root itself. It uses sudo for two things, and from Nearhost 0.8.0 only the sudo in a system directory, such as /usr/bin, never one found on your PATH.
- The hosts file. When a project starts and the block Nearhost owns in
/etc/hostsis not what it should be, Nearhost runs its own binary as root,sudo nearhost hosts apply --file /etc/hosts, which rewrites that block and nothing else. Ifsudostill holds your password from the last few minutes, this happens without asking again.--no-hoststurns it off. - Trusting the certificate authority. Only when you run
nearhost trustor accept the welcome box. On macOS it adds the root certificate to the System keychain withsecurity add-trusted-cert. On Linux it copies the certificate into your distribution’s anchors folder and runsupdate-ca-certificates,update-ca-trustortrust extract-compat. Whencertutilis installed, it also updates the stores that Firefox and, on Linux, Chromium-based browsers keep for themselves, as you, with no password.
On Windows, Nearhost uses User Account Control in place of sudo, and only for the hosts file: it runs its own binary as administrator to rewrite the block in C:\Windows\System32\drivers\etc\hosts, and Windows asks you to approve each time. Trusting the certificate authority needs no administrator rights there: it goes into your user’s certificate store, and Windows asks you to confirm it.
On Linux, binding ports 80 and 443 needs cap_net_bind_service. Nearhost itself never sets it. The install script offers to run sudo setcap when you run a downloaded copy from a terminal, and asks first. Through curl | sh, or nearhost update, it only prints the command, as nearhost doctor does.
The certificate authority
Section titled “The certificate authority”Nearhost creates its certificate authority on your machine the first time it starts: an ECDSA P-256 root, valid for ten years, with an intermediate that lasts 30 days. Certificates for your names last 7 days and renew automatically, within a minute of the laptop waking when one fell due during sleep. Nearhost issues them only for names you serve, and at start removes expired ones for names under a wildcard pattern.
Nothing limits the root to .test, the same as mkcert’s root. Anyone with its private key could make certificates your browser trusts for any domain. The key never leaves the caddy folder above, and that folder is readable only by you, but keep it out of dotfiles repositories and shared backups. See TLS and the proxy.
Ports on your laptop
Section titled “Ports on your laptop”While Nearhost runs, it listens on:
- 443 for HTTPS, over TCP and, for HTTP/3, UDP
- 80, only to redirect to HTTPS
- 6327 for Nearhost’s page
- one port on
127.0.0.1per forwarded route, and for aloopbackroute the same port on::1too, when the machine has IPv6 loopback - on Windows, one more port on
127.0.0.1per connected server, which coding agents on that server reach Nearhost through. It answers only requests that carry that server’s token.
443 and 80 listen on every interface, because macOS lets a program that is not root bind a low port only that way. On Windows they listen on loopback addresses only, so Windows Firewall does not ask about them. 6327 listens on 127.0.0.1 and ::1 only, on every system, unless you give a page port below 1024 on macOS without root, which listens on every interface. They answer only this machine: another computer’s connection is closed before it gets a certificate or a response. A project with docker_clients in its .nearhostrc is also answered for your Docker networks. Until Docker first reports them, Nearhost uses Docker’s default range, 172.16.0.0/12, which some home and office networks share.
--https-port, --http-port and --web-port move the ports, and --web-port 0 turns the page off. When Nearhost quits, all of them close.
Network requests
Section titled “Network requests”Nearhost makes these requests and no others. It has no telemetry, no analytics and no account.
- SSH to your servers, through your own
sshand~/.ssh/config. - The update check. At most once a day,
GET https://api.github.com/repos/nearhost/nearhost/releases/latest. SetNEARHOST_NO_UPDATE_CHECK=1to turn it off. - Preset registries. Only registries you have chosen to trust, from
raw.githubusercontent.com, when you add a project or manage presets. Each preset is checked against the hash in the registry’s index. With no trusted registry, Nearhost requests nothing. See Presets and registries. - DNS. To decide which names need a hosts entry, Nearhost asks your configured nameserver for names that do not end in
.test. - Docker, through its local socket, for projects with
docker_clients. nearhost update, only when you run it. It asks GitHub for the latest release, then runs your package manager or the install script, which download it.
Requests through the proxy
Section titled “Requests through the proxy”To show request bodies and send requests again, Nearhost keeps recent requests and responses in memory while it runs: the last thousand or so, bodies up to 64 KiB, 32 MiB in all. They are never written to disk and are gone when Nearhost quits. The log hides Cookie and Authorization headers. --no-capture turns capture off. See The request log.
On your servers
Section titled “On your servers”Nearhost installs nothing on a server and opens no ports there. It runs your ssh, and through that connection it:
- runs
trueonce to check that the connection works - forwards each route’s port to your laptop
- reads files over SFTP:
.env,.env.local,.nearhostrc, Compose files and any files an enabled preset names - creates
~/.nearhost, readable only by you, with a socket for coding agents on the server - from Nearhost 0.12.0, on a server with a private runtime folder (
/run/user/<uid>, as systemd makes), createsnearhostin it, readable only by you, keeps the socket there, and links to it from~/.nearhost. SELinux on Fedora and its relatives stops sshd making a socket in a home folder - when the laptop runs Windows, writes the token for that socket beside it, as
~/.nearhost/<id>.token, readable only by you
When Nearhost quits, the forwards and the connection close. ~/.nearhost stays, and may hold a stale socket or link that the next connection replaces. The system clears the runtime folder when your last session on the server ends. A .nearhostrc written by nearhost export stays in the project. See SSH transport.
What coding agents can do
Section titled “What coding agents can do”A coding agent reaches Nearhost through a socket that only your user can open, and sees only the projects of the machine it runs on. Without asking you, it can list those projects, run nearhost doctor on a folder, and ask Nearhost to reload a project’s .nearhostrc. Nearhost applies changes such as ports and new .test hosts straight away and saves them to config.yaml; the agent never edits that file itself. Anything else, including other domains, wildcards, localhost and docker_clients, waits for you to approve it. See How agents reach Nearhost.
Undo everything
Section titled “Undo everything”- Run
nearhost untrustto stop your system and browsers trusting the certificate authority. Add--delete-keyto delete its private key and the certificates it issued as well. - Run
nearhost hosts cleanto remove the block from/etc/hosts. - On Linux, the port capability goes with the binary when you uninstall it. To drop it and keep Nearhost, run
sudo setcap -ron the binarynearhost doctornames. - Uninstall Nearhost the way you installed it, such as
brew uninstall nearhostornpm uninstall -g @nearhost/cli. For the PowerShell installer, delete%LOCALAPPDATA%\Programs\nearhostand remove it from your userPATH. - Delete
~/.config/nearhost, the data folder that holdscaddy,~/.cache/nearhostand~/.nearhost. On Windows, delete%APPDATA%\nearhost,%LOCALAPPDATA%\nearhostand~\.nearhost. - On each server, delete
~/.nearhost, and any.nearhostrcyou no longer want.
Run steps 1 and 2 before step 4, while the nearhost command still exists.
Reporting a problem
Section titled “Reporting a problem”If you find a way around any of this, report it privately, as the security policy explains. Please don’t open a public issue.