DocsGetting StartedInstallation

Installation

ngstone is one Go module producing two binaries with different install stories. The agent (ngstone) has prebuilt installs for macOS and Linux. The edge (ngstoned) is server infrastructure you deploy deliberately, with a reviewed installer or by hand.

Requirements#

Installing the agent via Homebrew or the install script needs nothing but the internet — no Go toolchain required. Building either binary from source needs Go 1.25; both cmd/ngstoned and cmd/ngstone live in the same module, so a single go build invocation per binary is all the toolchain you need.

Installing the agent#

Two installers are verified working today, both installing just the ngstone binary:

$ brew install emilio-kariuki/tap/ngstone

brew install ngstone (short form)

The short form without the full tap path requires tapping and trusting the tap first — Homebrew 6 requires explicit trust for third-party taps:

$ brew tap emilio-kariuki/tap
$ brew trust emilio-kariuki/tap
$ brew install ngstone

The install script detects OS and architecture, downloads the matching release binary from github.com/emilio-kariuki/ngstone (currently v0.1.0), and installs it — no Go toolchain touched. Override the version or install directory with the NGSTONE_VERSION and NGSTONE_INSTALL_DIR environment variables.

Installing the edge (VPS)#

On an Ubuntu or Debian VPS, deploy/install-edge.sh from a checkout downloads the release binary, verifies its checksum, and sets up the systemd unit, secrets, and firewall — see Fast path installer. Its --from-source option builds ngstoned from the checkout with Go instead, which DNS providers other than Cloudflare need until a release that includes them is published.

$ sudo ./deploy/install-edge.sh --domain example.com --email you@example.com \
--dns-provider digitalocean --from-source --acme-ca staging

To install by hand, cross-compile it for linux/amd64 and copy it over, or build directly on the VPS if you'd rather not cross-compile. It has no install-time dependencies beyond the binary itself and a place to keep its certificate cache. See Deployment & systemd for running it as a managed service.

Building from source#

The Makefile wraps the common build targets: a local build, tests, a Linux/amd64 cross-compile for the VPS, and a deploy target that scps the result over.

$ make build
$ ./bin/ngstone version
$ ./bin/ngstoned -version

make deploy is the fast path from a source change to a binary sitting on the VPS, ready for a systemd restart.

Verifying the install#

Both binaries embed a version string injected at build time via -ldflags. Confirm a build or install worked with:

$ ngstone version
ngstone v0.1.0 (commit 3f1a9c2, built 2026-06-01T12:00:00Z)