Quickstart
This walks through the whole path: standing up the edge on a VPS you control, then pointing the agent at a local port from your laptop. No dashboard, no account creation — just two binaries and one short-lived, per-tunnel credential.
Prerequisites#
- 1
A Linux VPS
Anything that can run a static Go binary and accept inbound connections on ports 80, 443, and 4443. - 2
A domain with wildcard DNS
A domain such asexample.comwith a wildcard record (*.example.com) and an apex record (example.com) both pointing at your VPS's IP address. - 3
DNS hosted on a supported provider
The edge obtains its certificates through DNS-01, so it needs an API credential for the zone: Cloudflare (the default), Route 53, DigitalOcean, Hetzner, Vultr, OVH, deSEC, or Bunny. See Choosing a DNS provider. - 4
The ngstoned binary
Release archives includengstonedandngstone. Providers other than Cloudflare need a build from source (Go 1.25) until a release that includes them is published. The agent has prebuilt installs (below), so you don't need Go on your laptop.
Initialize durable storage and generate a scoped credential#
The edge uses SQLite by default for tunnel names, credentials, leases, policies, domains, and audit history. Issue a short-lived credential through the loopback management API; only a hash is stored and the plaintext is printed once.
$ ngstone admin credentials issue --server http://127.0.0.1:4041 \ --subdomain demo --ttl 24hcredential <id> issuedtoken: <save this value on the laptop>Start the edge#
On the VPS, run ngstonedwith your domain, a certificate contact email, and the chosen DNS provider's credentials in the environment (Cloudflare by default, or select --dns-provider). SQLite is used automatically; set NGSTONE_DATABASE_URL to a PostgreSQL URL for multiple edge servers:
$ NGSTONE_CF_API_TOKEN="$CF_API_TOKEN" \ ngstoned --domain example.com --cert-email you@example.comFor another provider, add --dns-provider NAME and set its variables instead; ngstoned -dns-provider help lists them. On Ubuntu or Debian, deploy/install-edge.sh does all of this, generates the token, and installs a systemd unit.
The edge requests two independent TLS certificates via DNS-01 — a wildcard for tunnel traffic and an apex certificate for the control plane on port 4443 — then starts listening. For anything beyond a quick trial, run it under systemd; see Deployment & systemd.
Install the agent#
On your laptop, install the agent binary:
$ brew install emilio-kariuki/tap/ngstone# or$ curl -fsSL https://raw.githubusercontent.com/emilio-kariuki/ngstone/main/install.sh | shAuthenticate#
Verify the scoped token from earlier against your edge, and save it locally:
$ ngstone auth "$TOKEN" --server example.com:4443verified against example.com:4443 and savedThe server address is saved with the token, and the certificate is verified against its host, so later commands need no further flags.
Start tunneling#
Point the agent at any local port. Without --subdomain, the edge assigns a random name:
$ ngstone port 3000$ ngstone port 3000 --subdomain demo