DocsGetting StartedQuickstart

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

    A Linux VPS

    Anything that can run a static Go binary and accept inbound connections on ports 80, 443, and 4443.
  2. 2

    A domain with wildcard DNS

    A domain such as example.com with a wildcard record (*.example.com) and an apex record (example.com) both pointing at your VPS's IP address.
  3. 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. 4

    The ngstoned binary

    Release archives include ngstoned and ngstone. 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 24h
credential <id> issued
token: <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.com

For 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 | sh

Authenticate#

Verify the scoped token from earlier against your edge, and save it locally:

$ ngstone auth "$TOKEN" --server example.com:4443
verified against example.com:4443 and saved

The 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

Next steps#