Introduction

ngstone is a personal, self-hosted alternative to ngrok. You run the edge on your own Linux VPS, point a wildcard domain at it, and run the agent next to whatever you're building. No dashboard, no account, no third party sitting between your laptop and the internet.

What is ngstone?#

It's two binaries and one shared Go module. There is no managed service, no signup flow, and no traffic that touches infrastructure you don't control — everything you tunnel stays between your VPS and your machine.

The two binaries#

ngstone splits cleanly into an edge process that lives on the public internet and an agent that lives on your dev machine.

How a request flows#

The agent always dials out — the VPS never connects into your laptop. That means no inbound firewall holes at home and no NAT traversal to worry about. One long-lived TLS TCP connection carries a yamux session between the two; the first stream on that session is a dedicated control stream, and every proxied HTTP request gets its own stream.

browser ──► ngstoned :443 ──► yamux session ──► ngstone agent ──► localhost:3000

HTTP and HTTPS tunnels are all v1 supports. The wire protocol is deliberately shaped — a Kind field on the bind and stream messages — so raw TCP tunnels can be added later without a protocol version bump.

What v1 covers#

A handful of guiding principles shape every decision in this project, in priority order:

• stdlib-first — reach for the Go standard library before a dependency
• boring over clever — predictable behavior beats a clever abstraction
• one path per feature — no alternate code paths to keep in sync
• everything flow-controlled — a slow reader backpressures the whole pipe
• nothing unbounded in memory — every buffer has a stated cap

Out of scope#

The following are explicitly out of scope for v1:

• Native gRPC and h2c backends
• Defending against volumetric DDoS beyond your VPS's own capacity
• VPS compromise — the edge is treated as trusted infrastructure
• OAuth-grade authentication in front of tunnels