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 build and deploy deliberately — it is not something to curl-pipe onto a box.

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)#

ngstonedisn't distributed as a release binary or a package — it's built and copied to the VPS deliberately. Cross-compile it for linux/amd64and 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)

PreviousQuickstart NextCore Concepts