Use a remote machine's localhost from your laptop.
Mirrors a dev box's ports over the SSH you already use.
About
·
Install
·
Documentation
·
Contributing
·
Developing
If you ssh foo into a dev box, run kamui foo instead. Kamui watches which
TCP ports are listening on the remote machine's loopback and opens the same
ports on your laptop. A dev server on remote port 3000 shows up at
http://localhost:3000 in your browser, in curl, and everywhere else. So do
OAuth redirects back to localhost, like the one at the end of an MCP sign-in.
Nothing gets installed on the remote side.
Warning
Every process on your laptop can reach the mirrored services, and browsers
treat them as localhost. Only use Kamui with hosts you trust.
I do my development on an always-on remote machine, so agents keep working when I close my laptop or lose Wi-Fi. The laptop just streams terminals.
The browser was the problem. An agent would start a dev server and print
http://localhost:3000, which meant the remote machine in its terminal and my
laptop in my browser. I kept a growing list of SSH forwards to paper over it:
Host foo
LocalForward 3000 localhost:3000
LocalForward 3001 localhost:3001
LocalForward 5173 localhost:5173
LocalForward 5432 localhost:5432Every new port meant editing that list and reconnecting, on every laptop.
MCP sign-ins broke it completely. An agent on the remote machine prints an
OAuth link, I open it on my laptop, and the provider redirects to
http://localhost:<port>/callback, a port the agent opened a moment ago,
usually a random one. The redirect landed on my laptop and the sign-in failed.
No list of forwards can cover a port that changes every time.
Kamui finds the ports for me, including those short-lived callback ports. It
uses the SSH setup I already have, keeps remote services bound to loopback,
and doesn't touch the repository. Tailscale or any other network works, as long
as plain ssh does.
brew install narasaka/tap/kamui # macOS: menu bar app + CLI
brew install narasaka/tap/kamui-cli # CLI only, macOS or Linux
go install github.com/narasaka/kamui/cmd/kamui@latestKamui runs on macOS and Linux, on either end. You need OpenSSH locally. The remote machine needs an SSH server with TCP
forwarding and one of ss, lsof, or netstat. See
installing and upgrading for details.
kamui foo # mirror foo's ports
kamui status # sessions, ports, conflicts
kamui stop foo # or: kamui stop --all
kamui foo --include-port 443 # ports under 1024 are opt-in
kamui doctor foo # check your setupThe destination can be an alias from ~/.ssh/config, a hostname, or
user@host. Keep ports, jump hosts, and keys in your SSH config; Kamui passes
the destination to OpenSSH as is.
Start your services the way you always do. New ports show up on your laptop within about a second and go away when the remote service stops.
On macOS 13 or later, the menu bar app lists your sessions and their ports,
opens a port in your browser with one click, and connects to hosts from your
SSH config. It asks for passphrases and host-key decisions itself, and it
carries its own kamui, so you never need a terminal. The app and the CLI share
the same sessions: start one in either and stop it from the other. See
the menu bar app.
kamui browser foo opens an isolated browser profile whose localhost points
at the remote machine. It doesn't open ports for other programs on your laptop. See
the CLI reference for its modes and
caveats.
kamui doctor foochecks the usual suspects.- If status says authentication is required, run
kamui fooin a terminal, or choose Reconnect in the menu bar app, and answer the prompt. kamui logs -fstreams OpenSSH's diagnostics.- A port that's already taken on your laptop stays with whoever has it.
kamui statuslists it as a conflict.
- How it works
- CLI reference
- Configuration
- Install, upgrade, and release
- Menu bar app
- Design decisions
make check # gofmt, golangci-lint, go vet, go test -race
make check-macos-app # Rust format, lint, and tests for the menu bar app
make macos-app # build dist/Kamui.appsite/ is the Astro site for kamui.narasaka.dev.
It renders the user-facing pages in docs/ at build time, so editing a doc
updates the site. Run pnpm install && pnpm dev there to preview it. Cloudflare
Workers Builds deploys it: pushes to main that touch site/ or docs/ go to
production, and other branches get a preview URL.
Commit subjects use scope: description
(Scoped Commits).