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

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 ngstone.site with a wildcard record (*.ngstone.site) and an apex record (ngstone.site) both pointing at your VPS's IP address.
3. 3

   Go 1.25, to build the edge

   ngstonedisn't distributed as a prebuilt binary — build it from source for the VPS's architecture. The agent, by contrast, has prebuilt installs (next section), so you don't need Go on your laptop.

Generate a token#

There's no ngstone token command — generate one with a couple of standard tools. The edge only ever stores the hash; keep the plaintext for the agent.

$ TOKEN=$(openssl rand -base64 32 | tr '+/' '-_' | tr -d '=')
$ HASH=$(printf '%s' "$TOKEN" | shasum -a 256 | cut -d' ' -f1)   # sha256sum on Linux

Start the edge#

On the VPS, run ngstoned with your domain, a certificate contact email, a Cloudflare API token scoped to Zone:DNS:Edit, and the token hash from above:

$ ngstoned --domain ngstone.site --cert-email you@ngstone.site \
    --cf-api-token "$CF_API_TOKEN" --token-sha256 "$HASH"

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 plaintext token from earlier against your edge, and save it locally:

$ ngstone auth "$TOKEN"
verified against ngstone.site:4443 and saved

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#