Run it anywhere.
Open it here.

Nearhost is a terminal app that opens a project running on one of your other machines at a local https://myapp.test, over the SSH config you already have. You install nothing on the server, and cookies, OAuth redirects, WebSockets and hot reload behave as they do on localhost. A coding agent on that machine can use it too: it asks to add the project, open a preview or show you a plan, and you say yes.

curl -fsSL https://nearhost.dev/install.sh | sh
Read the docs

Open source under MIT, for macOS and Linux. Also brew install nearhost/tap/nearhost or npx @nearhost/cli.

nearhost — 120×36 click to use the keys
∩ nearhost proxy ● :443 · CA trusted · hosts ok · 1 problem
myapp https://myapp.test ● running · up 2h 14m
server minipreset laravel, vitepath ~/code/myapp
portrolelabellocalstatus
8080webapp (APP_PORT)52114●
5173loopbackVite (vite.config)5173●
1 ignored: 5432 · i show
▲ Vite rejects requests for myapp.test unless it is in server.allowedHosts. y copy fix
log following ●
12:04:01forward127.0.0.1:52114 → mini:8080
12:04:01forward127.0.0.1:5173 → mini:5173
12:04:02proxyhttps://myapp.test ready
12:04:09GET/200 41ms
12:04:09GET/@vite/client200 3ms
12:04:31GET/dashboard200 88ms
12:04:44POST/login302 63ms
12:05:02hmrsrc/pages/Dashboard.vue
12:05:13GET/api/projects?sort=owner500212ms
12:05:14GET/api/projects200 54ms
12:05:20GET/favicon.ico404 1ms
12:05:41hmrsrc/components/Card.vue
12:05:42GET/dashboard200 64ms
12:06:03GET/api/projects?page=2200 49ms
12:06:03GET/api/user200 18ms
12:10:10GET/settings200 77ms
· · · · · · · · · · myapp 3/5

Every key works. No servers were harmed. Click in and press ?

The code runs on another machine. Your browser is on this one.

Today that means an ssh -L flag for every port, plain HTTP that breaks secure cookies and OAuth callbacks, and hot reload that fails when a port is missed. Nearhost sets that up once per project and gives each one a name you can open.

Your agent asks. You say yes.

Coding agents on a server can add the project to Nearhost, open the preview they just started, and show you the plan they wrote, in the browser on your laptop. Nearhost asks you first, and the agent gets the address once you say yes.

Coding agents
On mini, over SSH
claude on mini
Claude Code v2.1.301
Opus 5.5 · Claude Max
~/code/myapp
❯ /nearhost:nearhost add
Proposing this project to Nearhost
⎿ $ sh ~/.claude/skills/nearhost/scripts/nearhost.sh propose .
✢ Combobulating… (2s · esc to interrupt)
Ran 1 shell command
⏺ I've proposed myapp to Nearhost. Review it in Nearhost on ecs@macbook.
Waiting for your answer in Nearhost
⎿ $ sh ~/.claude/skills/nearhost/scripts/nearhost.sh wait 7c1f04a2e9b3d851
✻ Percolating… (14s · esc to interrupt)
Ran 1 shell command
⏺ Added. myapp is running at https://myapp.test, served from port 5173 on mini.
✻ Brewed for 21s
❯
? for shortcuts
On your laptop
nearhost
∩ nearhostproxy ●
Nearhost
running 12 of 2 projects
Added myapp, as an agent on mini proposed.
Add project · routes5 of 7
Proposed by an agent on mini
server mini
path /home/dev/code/myapp
port role label
▌[x] 5173 ‹ web › vite
[ ] 5432 ignore db
enter next · esc back
On mini, over SSH
codex on mini
>_ OpenAI Codex (v0.165.0)
~/code/myapp
› Brainstorm three layouts for the pricing page and show them to me in the browser
• I'll sketch three layouts and serve them from a preview on port 5173.
• Ran sh ~/.codex/skills/nearhost/scripts/nearhost.sh passthrough 5173 --label
│ "browser preview"
└ {"id":"3f9a61c0d2e7b845"}
• Approve it in Nearhost on ecs@macbook.
◦ Running sh ~/.codex/skills/nearhost/scripts/nearhost.sh passthrough-wait 3f9a61c0d2e7b845
• Ran sh ~/.codex/skills/nearhost/scripts/nearhost.sh passthrough-wait 3f9a61c0d2e7b845
└ {"state":"open","url":"http://localhost:5173"}
• The three layouts are open at http://localhost:5173/pricing on your laptop. Pick one and I'll build it.
Worked for 48s • 10:42 AM
• Working (2s9s • esc to interrupt)
› Ask Codex to do anything
GPT-6.1-Sol low · ~/code/myapp
? for shortcuts
On your laptop
nearhost
Browser preview
An agent on mini wants to open port 5173 on this laptop (browser preview).
y yes · n no
localhost:5173/pricing
Pricing page: three layouts
A · Three tiers
B · Usage slider
C · Comparison
On mini, over SSH
qwen on mini
>_ Qwen Code (v0.26.2)
Qwen OAuth | coder-model (/model to change)
~/code/myapp
Tips: Type / to open the command popup; Tab autocompletes slash commands and saved prompts.
> Write a plan for the checkout refactor and open it for me to review
◆︎ I'll write the plan to docs/plans/2026-10-28-checkout.md, then open it in your browser.
✓ WriteFile Writing to docs/plans/2026-10-28-checkout.md
1 # Checkout refactor
2
3 Move tax and shipping into one Quote service.
4
5 - [ ] Add the Quote service and its tests
✓ Shell sh ~/.qwen/skills/nearhost/scripts/nearhost.sh open docs/plans/2026-10-28-checkout.md --label plan
{"id":"9b2e44d1a07c3f68","expires_at":"2026-10-28T09:52:00Z"}
◆︎ Approve it in Nearhost on ecs@macbook.
⊷ Shell sh ~/.qwen/skills/nearhost/scripts/nearhost.sh open-wait 9b2e44d1a07c3f68(9s · timeout 2m)
✓ Shell sh ~/.qwen/skills/nearhost/scripts/nearhost.sh open-wait 9b2e44d1a07c3f68
{"state":"open","url":"https://localhost:6327/d/Qm7xK2v9pLr4Tn8wZc3hJA/docs/plans/2026-10-28-checkout.md"}
◆︎ The plan is open in your browser. It always shows the file as it is now, so reload it after I make changes.
⠋ Brewing fresh bytes... (2s9s · esc to cancel)
> Type your message or @path/to/file
Enter to steer · Ctrl+Q to queue · ⏸ Ask permissions (shift + tab to cycle)2.1% context used
On your laptop
nearhost
Show a document
An agent on mini wants to show docs/plans/2026-10-28-checkout.md (plan)
Nearhost will serve files in /home/ecs/code/myapp, except dotfiles.
y yes · n no
localhost:6327/d/Qm7xK2v9pLr4Tn8wZc3hJA/docs/plans/2026-10-28-checkout.md
Checkout refactor

Move tax and shipping into one Quote service, so the cart and the payment step agree on the total.

Tasks
  • Nothing is added, forwarded or opened until you say yes in Nearhost. Claude Code can also be given Always allow for previews and documents.
  • On a server, the agent reaches Nearhost through the SSH connection Nearhost already has. No port is opened on the server.
  • Works in Claude Code, Codex, Qwen Code, Cursor, Gemini CLI and any agent that reads skills.
Give your agent the skill
npx skills add nearhost/nearhost -g

Set up in three steps, with nothing to install on the server.

If ssh mini works without a prompt, Nearhost works. It reuses your SSH config, including ProxyJump, agents and keychain identities, and installs nothing on the remote machine.

01

Add a server

Pick a host alias from ~/.ssh/config or type user@host. Nearhost checks that it connects without a prompt and shows OpenSSH's own output if it doesn't.

Adding a server
02

Add a project

Point at a path. Nearhost reads its .env over SFTP, and with the official presets its Compose and Vite config, and proposes the ports: which one is the web app, which need a loopback forward, which to ignore.

Adding a project
03

Open it

It starts as soon as you add it: Nearhost adds a hosts entry, issues a certificate from its local CA and routes https://myapp.test through the SSH tunnel. WebSockets and hot reload pass through the same tunnel. Press o to open it.

The first run
The path of one request
laptop · browserhttps://myapp.test
laptop · nearhostCaddy :443, TLS
laptop · openssh-L 52114 → localhost:8080
mini · untouchedlocalhost:8080 · your dev server

What the tunnel handles: HTTPS, hot reload and WebSockets.

Real HTTPS, trusted once

Secure cookies, OAuth callbacks and service workers need HTTPS, so every alias gets a real certificate. Nearhost creates its own local CA on first run and you trust it once. No shared key ships in the binary, so nobody else can mint certificates for your .test names.

TLS and the proxy

Hot reload and WebSockets pass through

Nearhost can forward a dev server's port to the same number on your laptop. Asset URLs that point at localhost still resolve, so hot reload connects with the remote config untouched.

Dev servers and hot reload

Port discovery

Nearhost reads port variables from .env. Presets from a registry you choose to trust add Compose, Vite and Laravel Sail, and warn about port clashes and a missing allowedHosts before you start. For anything else, give it the web port.

How discovery works

Runs on your SSH config

Nearhost shells out to OpenSSH, so Include, Match, ProxyJump, agent forwarding and keychain identities apply. It stores nothing but the host name.

SSH transport

Local projects too

The local server needs no setup. Projects on your laptop get the same alias and certificate, so one tool covers the laptop and the servers.

Add a project

Headless when you want it

nearhost up starts projects without the UI. nearhost doctor checks ports, trust, hosts and each server. Config is one YAML file you can edit by hand.

CLI reference

How it compares to ssh -L, mkcert, local dev apps, VPNs and tunnels.

Nearhost is for your own machines and your own browser. It is the wrong tool for showing work to someone else.

ssh -L by hand

The same OpenSSH forwards, typed per port and retyped after every dropped connection, with no hostname and no certificate.

Nearhost keeps one supervised SSH connection per server, adds and removes forwards while it runs, and puts a trusted https://name.test in front.

mkcert

Creates a local certificate authority and the certificates it signs. The rest is up to you: a server or proxy set up with them, a hosts file entry, and for a project on another machine, an SSH forward.

Nearhost does all of that. It creates its own certificate authority on first run, so you do not need mkcert, and signs a certificate for each name you add.

VS Code and other editor port forwarding

Convenient while the editor window is open. You get localhost:port URLs, so cookies and OAuth settings differ from a named HTTPS origin.

Nearhost runs in a terminal, independent of any editor, and each project keeps the same HTTPS name every day.

Laravel Herd, OrbStack and other local dev apps

Herd serves PHP sites from this Mac or PC at .test. OrbStack gives each container on this Mac an HTTPS name under .orb.local. Both serve what runs on the machine in front of you.

Nearhost serves projects on this machine and on any other you reach with ssh, for any stack, at names you choose, on macOS and Linux.

Tailscale or another VPN or mesh network

Makes the machine reachable, which usually means an agent on every machine and a dev server that listens beyond localhost.

Nearhost installs nothing on the server. The dev server keeps listening on localhost and is reached over SSH.

ngrok or another public tunnel service

Built for sharing. Your traffic goes through someone else's relay to a public URL, usually behind an account.

Nearhost has no relay, no account and no public URL. Use a tunnel service when a client needs to see the page.

Fix ngrok assets that point at localhost

Your traffic stays between your machines.

Nearhost has no relay, no account and no public hostname. Your .test names resolve from a marked block in /etc/hosts that Nearhost owns, and requests travel over your own SSH connection to the server.

  • →Runs in the foreground. Quit it and the tunnels close.
  • →Asks for your password only when /etc/hosts needs a change, and says why in the same box.
  • →nearhost untrust and nearhost hosts clean undo the trust store and hosts changes.
Everything Nearhost changes on your machine
# /etc/hosts

127.0.0.1   localhost
::1         localhost
…

# nearhost:start
127.0.0.1 myapp.test
::1 myapp.test
127.0.0.1 otherapp.test
::1 otherapp.test
127.0.0.1 website.test
::1 website.test
# nearhost:end

Questions before you install.

Does Nearhost install anything on the server?

No. Nearhost runs on your laptop and shells out to OpenSSH. It reads files such as .env over SFTP, and adds only a private ~/.nearhost folder holding a socket, so a coding agent on the server can reach it. It writes a .nearhostrc to your project only when you run nearhost export. The server needs SSH that connects without a prompt, with SFTP and TCP forwarding allowed, as most servers do.

Which operating systems does it run on?

Nearhost runs on macOS and Linux, on Apple silicon, Intel and ARM. The server can be any machine you reach with ssh: a desktop under the desk, a home server, a VPS or a VM. Linux needs one extra step to bind ports 80 and 443 and to trust the certificate in your browser.

Does it work with my framework?

Nearhost routes ports, so it works with any HTTP dev server, such as Laravel, Rails, Django, Next.js or Vite. It finds ports in .env, and presets add Docker Compose, Vite and Laravel Sail. For anything else, give it the web port.

Can I share a Nearhost address with someone else?

No. A .test name resolves from /etc/hosts on your laptop and its certificate is trusted only there, so the address works in your own browser and nowhere else. To show a page to a client, use a public tunnel service such as ngrok.

What happens when the SSH connection drops?

Nearhost keeps one supervised SSH connection per server and reconnects by itself. While it is down, the projects on that server show as degraded and requests get a 502. Once ssh works again, press r to reconnect straight away.

Is Nearhost free?

Yes. Nearhost is open source under the MIT licence, with no account and no sign-up. Install it with the shell script, Homebrew or npm.

Install Nearhost.

One static binary for macOS and Linux, on Apple silicon, Intel and ARM. The first run offers to trust its local CA, then helps you add your first project.

Shell
curl -fsSL https://nearhost.dev/install.sh | sh
Homebrew
brew install nearhost/tap/nearhost
npm
npx @nearhost/cli

Linux needs one extra step to bind ports 80 and 443 and to trust the certificate in your browser. The install guide has the commands, and nearhost doctor tells you what is missing.