ngstone.
DocsReferenceConfiguration

Configuration

The agent keeps a small JSON config file; the edge is flags and environment variables only, with no config-file dependency.

Agent (ngstone)#

ngstone auth, ngstone config set, and ngstone logout read and write:

$XDG_CONFIG_HOME/ngstone/config.json
# falls back to ~/.config/ngstone/config.json if XDG_CONFIG_HOME is unset
tokenstring
Saved by ngstone auth <token> after it verifies against the edge. Cleared by ngstone logout.
serverstring
Saved by ngstone auth or ngstone config set server <addr>. Falls back to ngstone.site:4443 if never set.

The file is written mode 0600 inside a 0700directory, via a temp-file-plus-rename so a crash mid-write can't corrupt it. See ngstone config for the commands that read and write it.

Edge (ngstoned)#

-domainstringdefault: ngstone.site
Base domain used to build tunnel hostnames and the two managed certificates.
-publicstringdefault: :443
Public HTTPS listen address.
-controlstringdefault: :4443
Control-plane listen address — what the agent dials.
-httpstringdefault: :80
HTTP redirect listen address. Unused with -insecure.
-opsstringdefault: 127.0.0.1:4041
Loopback ops endpoint (expvar, /healthz, pprof). Empty disables it.
-public-schemestringdefault: https
Scheme advertised in BindOK.URL — http or https.
-token-sha256stringrequired
Hex-encoded SHA-256 of the shared auth token. Defaults to $NGSTONE_TOKEN_SHA256. See Generating a token.
-insecurebooldefault: false
Run with no TLS anywhere and no certificate management. Dev/test only.
-acme-castringdefault: staging
ACME CA: staging or production. A config mistake against production can rate-limit the domain for a week.
-cert-emailstringrequired
ACME account email. Required unless -insecure.
-cert-storagestring
certmagic.FileStorage path; must match the systemd StateDirectory.
-cf-api-tokenstringrequired
Cloudflare API token scoped to Zone:DNS:Edit on the one zone. Required unless -insecure. Defaults to $NGSTONE_CF_API_TOKEN.

Every value in the timeouts and limits table — request timeouts, body caps, rate limits, concurrency caps — is also flag-overridable on the edge (-read-header-timeout, -idle-timeout, -max-header-bytes, -max-body-bytes, -response-header-timeout, -per-ip-rate, -per-ip-burst, -per-ip-lru, -global-inflight, -per-session-inflight, -handshake-concurrency, -unauth-sessions). See Limits & timeouts for the full set and their defaults.

Environment variables#

NGSTONE_TOKENagent env
Fallback token source for ngstone port, below a--token flag and above the saved config file.
NGSTONE_TOKEN_SHA256edge env
Preferred way to pass the token hash to ngstoned instead of -token-sha256.
NGSTONE_CF_API_TOKENedge env
Preferred way to pass the Cloudflare token to ngstoned instead of -cf-api-token.

Never pass secrets as flags

/proc/<pid>/cmdline is world-readable on stock Linux, so anything passed as an ExecStart flag is readable by any local user via ps auxww. Load secrets from EnvironmentFile= instead.

Precedence#

On the edge, an explicit flag always wins over its environment fallback; anything left unset falls back to its documented default.

On the agent, resolving the token or server address for ngstone port follows this chain:

1. Flaghighest precedence
--token / --server.
2. Environmenttoken only
NGSTONE_TOKEN. There is no environment override for the server address.
3. Config file
Whatever ngstone auth or ngstone config set last saved.
4. Defaultserver onlydefault: ngstone.site:4443
Used only if nothing above set a server address. There is no default token — an unresolved token is a hard error.
PreviousCLINextThe wire protocol