Skip to content
narasakaPublic

About

Mirror a remote SSH host's localhost ports onto your laptop. Discovers listening TCP services over SSH, no remote install.

Topics

Resources

Contributing

Stars

5 stars

Watchers

0 watching

Forks

Repository files navigation

Kamui icon
Kamui

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

About

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.

Why

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:5432

Every 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.

Install

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@latest

Kamui 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.

Usage

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 setup

The 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.

Menu bar app

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.

Dedicated browser

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.

Troubleshooting

  • kamui doctor foo checks the usual suspects.
  • If status says authentication is required, run kamui foo in a terminal, or choose Reconnect in the menu bar app, and answer the prompt.
  • kamui logs -f streams OpenSSH's diagnostics.
  • A port that's already taken on your laptop stays with whoever has it. kamui status lists it as a conflict.

Documentation

Developing

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.app

site/ 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).

About

Mirror a remote SSH host's localhost ports onto your laptop. Discovers listening TCP services over SSH, no remote install.

Topics

Resources

Contributing

Stars

5 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages