DocsReferenceCLI

CLI

The ngstone command is built on the stdlib flag package — no cobra, no subcommand framework. The verbs are auth, admin, login, doctor, credentials, status, tunnels, observability, drain, up, preview, port, tcp, serve, start, service, ps, share, connect, shares, unshare, extend, kick, config, replay, logout, and version.

Overview#

ngstone <command> [arguments]
 
Commands:
auth <token> verify and save an auth token
admin manage a self-hosted edge over its ops API
login print the browser URL for OIDC management login
doctor diagnose local configuration and edge connectivity
status show edge health and metrics
tunnels list active tunnels
observability show per-tunnel metrics and latency
drain <hostname> gracefully drain a tunnel
credentials issue, list, or revoke scoped tunnel credentials
up start all tunnels from ngstone.json
preview <port|url> start a disposable preview URL
port <port|url> expose a local port or URL through the tunnel
tcp <port|host:port> expose a raw TCP service through the tunnel
share <preset>... share local databases with teammates via a link
connect <link> connect to a shared database through a link
shares list live shares on the edge (--watch tails their events)
unshare <id> revoke a share
extend <id> <duration> move a share's expiry
kick <id> <connector> remove one connector from a share
config view or set local configuration
replay <file> replay a saved request against a local target
logout remove the saved auth token
version print the ngstone version

ngstone auth#

Verifies a token against the edge's control plane, then saves the token and server address to the config file. Nothing is written to disk until the edge has confirmed the token is valid.

$ ngstone auth <token>
verified against ngstone.site:4443 and saved
--serverstring
Edge control-plane address to verify against. Defaults to the config file's saved server, or ngstone.site:4443 if neither is set.
--transportstringdefault: auto
Control transport. auto tries raw TLS first and falls back to the authenticated WebSocket endpoint on HTTPS port 443; use raw or websocket to force one path. quic carries the session over UDP to an edge started with -quic; it is never part of auto and never falls back.
--insecurebooldefault: false
Dial the control plane in plaintext. Dev/test only — no certificate validation happens at all.
--server-namestring
TLS ServerName/SNI to verify against. Defaults to the host in the server address, so example.com:4443 verifies example.com. Ignored with --insecure.
--pinstring
Optional SPKI pin, e.g. --pin sha256/BASE64, checked in addition to normal chain validation. Off by default.

For a self-hosted edge, pass its bare domain; the server address is saved, so later commands need no flags:

$ ngstone auth <token> --server example.com:4443
verified against example.com:4443 and saved

A bad token or an unreachable server exits non-zero with a specific, actionable message rather than a generic failure. Agent releases older than the --server-name default need --server-name example.com on every command.

ngstone login#

Prints the edge's browser OIDC login URL. Authentication happens in the browser and creates a session for the edge dashboard; it does not write an OIDC secret or session cookie to the agent config file. The same command is available as ngstone admin login.

$ ngstone login --server https://edge.example.com:4041
Open this URL in your browser to sign in with OIDC:
https://edge.example.com:4041/api/v1/auth/oidc/start
$ ngstone admin login --json
--serverstring
Management API URL. Defaults to NGSTONE_ADMIN_SERVER orhttp://127.0.0.1:4041.
--jsonbooldefault: false
Print a JSON object containing the browser login URL.

ngstone doctor#

Runs local and remote readiness checks for the agent and self-hosted edge. It checks config-file permissions, token presence, transport settings, control-plane DNS/TCP reachability, token authentication, optional management API health/authentication, and OIDC environment configuration.

$ ngstone doctor
$ ngstone doctor --admin-server https://edge.example.com:4041 --admin-token "$NGSTONE_ADMIN_TOKEN"
$ ngstone doctor --json
--serverstring
Control-plane address override. Defaults to the saved config orngstone.site:4443.
--tokenstring
Tunnel token override. Defaults to NGSTONE_TOKEN or the saved agent config.
--transportstringdefault: auto
Control transport to validate and use for authentication:auto, raw, websocket, or quic.
--admin-serverstring
Optional management API URL. HTTPS is required outside loopback unless --insecure is explicitly set.
--admin-tokenstring
Management bearer token override. Defaults to NGSTONE_ADMIN_TOKEN.
--timeoutdurationdefault: 5s
Maximum time for each network check.
--jsonbooldefault: false
Emit a machine-readable report with ok and a list of checks. Exit status is non-zero when any check fails.

ngstone credentials#

Manages the edge's versioned per-tunnel credential file. The edge stores only token hashes; the plaintext token is printed once byissue and cannot be recovered later. Run these commands on the edge host as the account that owns the credential file.

$ ngstone credentials issue --file /var/lib/ngstoned/credentials.json --subdomain demo --ttl 24h
credential 7109b9faf3f8b5d38086d3e0566c1296 issued
token: nst_...
$ ngstone credentials list --file /var/lib/ngstoned/credentials.json
$ ngstone credentials revoke 7109b9faf3f8b5d38086d3e0566c1296 --file /var/lib/ngstoned/credentials.json
issuesubcommand
Creates an HTTP credential scoped to --subdomain, or a TCP credential scoped to --remote-port with --kind tcp. --kind share issues a credential for ngstone sharethat manages only its owner's shares. The default TTL is 24 hours and the maximum is 720 hours.
listsubcommand
Prints credential metadata and status. It never prints token material; add --json for machine-readable metadata.
revoke <id>subcommand
Revokes one credential. The edge notices active sessions on the next heartbeat.
--filepath
Credential file to manage. Defaults to NGSTONE_CREDENTIALS_FILE.

ngstone admin#

Manages a running self-hosted edge through its versioned management API. The default server is http://127.0.0.1:4041, so the usual VPS workflow is an SSH port-forward followed by these commands:

$ ssh -L 4041:127.0.0.1:4041 root@example.com
$ ngstone admin status
$ ngstone admin tunnels --json
$ ngstone admin credentials issue --subdomain demo --ttl 24h
$ ngstone admin credentials revoke <credential-id>
$ ngstone admin policies list
$ ngstone admin policies apply --name web --file traffic-policy.json
$ ngstone admin domains list
$ ngstone admin domains add --domain app.example.org --tunnel-id <tunnel-id>
$ ngstone admin domains activate <domain-id>
$ ngstone admin domains disable <domain-id>
$ ngstone admin tunnel drain demo

Operator shortcuts#

The common read-only operations have shorter aliases. They use the same NGSTONE_ADMIN_SERVER, NGSTONE_ADMIN_TOKEN, --server, --token, and --json options as the matching ngstone admin commands.

$ ngstone status
$ ngstone tunnels --json
$ ngstone observability
$ ngstone drain demo

Successful API responses use a {"data": ...} envelope. Errors use {"error": {"code": ..., "message": ...}}. Credential issue prints the plaintext token once; list never returns token material.

GET /api/v1/status
GET /api/v1/tunnels
GET /api/v1/credentials
POST /api/v1/credentials
DELETE /api/v1/credentials/{id}
GET /api/v1/policies
POST /api/v1/policies
DELETE /api/v1/policies/{id}
GET /api/v1/domains
POST /api/v1/domains
DELETE /api/v1/domains/{id}
POST /api/v1/domains/{id}/status
POST /api/v1/tunnels/{hostname}/drain
$ curl -X POST http://127.0.0.1:4041/api/v1/credentials -H 'Content-Type: application/json' -d '{"subdomain":"demo","ttl":"24h"}'
{"data":{"credential":{"id":"0123456789abcdef0123456789abcdef","kind":"http","subdomain":"demo","created_at":"2026-08-18T12:00:00Z","expires_at":"2026-08-19T12:00:00Z"},"token":"nst_<printed-once>"}}
statussubcommand
Show edge health, listeners, certificate state, request metrics, active tunnels, and recent events.
tunnelssubcommand
List active HTTP and TCP tunnels, connector health, capacity, and access-policy state.
observabilitysubcommand
Show per-tunnel request counts, approximate p50/p95/p99 latency, status-code counts, active connectors, reconnects, bytes, and credential lifecycle counters. Add --json for dashboards and automation.
domainssubcommand
Register a custom domain for an HTTP or TLS tunnel with add --domain NAME --tunnel-id ID; it stays pending and serves nothing. activate and disable need the administrator role. For HTTP tunnels the edge obtains a certificate automatically, or uses one from -custom-certs; see the README, Custom domains.
credentials issuesubcommand
Issue a scoped HTTP, TCP, or TLS credential. Use --kind tcp with --remote-port for a TCP tunnel, or --kind tls with --subdomain for a TLS passthrough tunnel. The default TTL is 24 hours and the maximum is 30 days.
credentials listsubcommand
List credential metadata without exposing plaintext tokens.
credentials revoke <id>subcommand
Revoke one credential independently of all other tunnels.
tunnel drain <hostname|subdomain>subcommand
Gracefully remove a tunnel from routing and ask all of its connectors to drain in-flight work.
--serverstring
Management API URL. Defaults to NGSTONE_ADMIN_SERVER orhttp://127.0.0.1:4041.
--tokenstring
Bearer token for the management API. Defaults to NGSTONE_ADMIN_TOKEN; prefer the environment so it does not appear in process listings.
--jsonbooldefault: false
Emit machine-readable JSON for the selected command.

Keep the ops listener private

Without an admin token hash, the management API accepts only loopback requests. With NGSTONE_ADMIN_TOKEN_SHA256, bearer auth is required for /api/v1, but the dashboard, metrics, health, and pprof endpoints remain separate. With OIDC enabled, browser users are mapped to viewer, operator, or admin from IdP groups and mutating requests require CSRF protection. Use SSH or a private network with a TLS-authenticated proxy; do not publish -ops directly.

ngstone up#

Starts every tunnel in a project file. By default it looks for ngstone.json, then .ngstone.json, in the current directory. The project file is separate from the saved credentials file; it never accepts a token field.

{
"tunnels": {
"web": {
"target": "3000",
"subdomain": "demo",
"host_header": "demo.localhost:3000",
"credential_env": "NGSTONE_WEB_TOKEN",
"multi_connector": true,
"connector_token_env": "NGSTONE_CONNECTOR_TOKEN",
"policy_file": "traffic-policy.json",
"ttl": "2h"
},
"grpc": {"target": "http://127.0.0.1:50051", "http2": true},
"api": {"target": "3001", "subdomain": "api"}
}
}
$ ngstone up
web: https://demo.ngstone.site -> http://127.0.0.1:3000
api: https://api.ngstone.site -> http://127.0.0.1:3001
 
$ ngstone up --file staging.ngstone.json --json
$ ngstone up --json --har requests.har
{"type":"tunnel","time":"2026-08-17T10:00:00Z","name":"web","kind":"http","target":"http://127.0.0.1:3000","state":"online","hostname":"demo.ngstone.site","url":"https://demo.ngstone.site","expires_at":"2026-08-17T12:00:00Z"}
--filestring
Project file to load. Defaults to ngstone.json or .ngstone.json in the current directory.
--jsonbooldefault: false
Emit one JSON Lines status event per tunnel state change to stdout; diagnostic logs stay on stderr.
--harstring
Write captured HTTP exchanges from all project tunnels to this HAR file when the process exits.
--har-include-sensitivebooldefault: false
Include authorization, cookie, and API-key headers in the HAR. The default redacts them.

Each tunnel can set kind (http or tcp), target, subdomain, host_header, remote_port, ttl, server, TLS options, basic_auth_file, and allow_cidr, policy_file, and multi_connector, and credential_env. See the project configuration reference.

ngstone preview#

Starts a disposable HTTP preview URL. The edge assigns a random hostname, and the tunnel always has a positive TTL; the default is two hours. This command rejects --subdomain so a preview cannot accidentally become a stable named tunnel.

$ ngstone preview 3000
$ ngstone preview 3000 --ttl 30m --json
$ ngstone preview 3000 --ttl 2h --no-tui
--ttldurationdefault: 2h
Required positive lifetime for the preview URL. Set a different duration such as 30m to shorten it.
--jsonbooldefault: false
Emit JSON Lines status events, including the URL and expires_at.
--no-tuibooldefault: false
Log plain output instead of opening the request inspector.
--harstring
Export captured HTTP exchanges when the preview exits.
--har-include-sensitivebooldefault: false
Include sensitive headers in the HAR instead of redacting them.

Preview accepts the target, host-header, auth, access-control, server, and TLS flags from ngstone port. It does not accept a requested subdomain.

TTL is not access control

The preview URL is public while it is live. Add --basic-auth or --allow-cidr when the preview contains private data; the TTL only limits how long the URL remains active.

ngstone replay#

Sends a replay file saved by the request inspector directly to a local target. The request never goes back through the public tunnel. Use--curl to print a command instead of sending it.

$ ngstone replay ngstone-replay-000000000001.json --target 3000
$ ngstone replay ngstone-replay-000000000001.json --target 3000 --json
$ ngstone replay ngstone-replay-000000000001.json --curl
$ ngstone replay request.json --curl --target http://127.0.0.1:3000
--targetport|url
Local port or full URL to receive the request. Required unless--curl is used; with --curl --target, the original host is preserved in the generated command.
--curlbooldefault: false
Print a shell-quoted cURL command and exit without sending the request.
--include-sensitivebooldefault: false
Include authorization, cookie, API-key, and related sensitive headers in --curl output. Redaction is the default.
--jsonbooldefault: false
Emit one JSON result containing status, headers, duration, and a base64 response body.
--timeoutdurationdefault: 30s
Maximum time to wait for the local response.

ngstone port#

Starts a tunnel to a local port or URL. This is the command that actually opens a connection to the edge and forwards traffic. When stdout is a terminal, it also opens a full-screen inspector dashboard showing every request and response live, with headers, decoded bodies, timing, and replay — see Using the request inspector.

$ ngstone port 3000
$ ngstone port http://127.0.0.1:3000
$ ngstone port 3000 --subdomain demo
$ ngstone port 3000 --host-header demo.localhost:3000
$ ngstone port 3000 --subdomain demo --multi-connector

The positional argument is either a bare port number (forwarded to http://127.0.0.1:<port>) or a full target URL. Flags may appear before or after it.

--subdomain, -sstring
Request a specific subdomain instead of a server-assigned one, e.g. --subdomain demo for demo.ngstone.site.
--host-headerstring
Host header sent to the local app. By default, the public tunnel hostname is preserved. Set it when the app expects a local tenant hostname, e.g. --host-header demo.localhost:3000.
--http2booldefault: false
Use a native HTTP/2 stream to the local target. Use an https:// target for TLS HTTP/2 or an http:// target for cleartext h2c. This is required for native gRPC trailers, streaming, and full-duplex behavior; ordinary HTTP/1.1 forwarding remains the default.
--multi-connectorbooldefault: false
Allow several agent processes to share the same named tunnel and load-balance requests across live connectors. Requires an explicit--subdomain and a shared per-tunnel connector token; use the flag and NGSTONE_CONNECTOR_TOKEN on every connector. A connector reconnect or shutdown drains only its own in-flight requests. HTTP-only.
--connector-tokenstring
Per-tunnel secret used to authorize membership in a multi-connector pool. Prefer NGSTONE_CONNECTOR_TOKEN so the secret is not exposed in the process command line.
--serverstring
Edge control-plane address override. Defaults to the config file or ngstone.site:4443.
--transportstringdefault: auto
Control transport. auto tries raw TLS first and falls back to the authenticated WebSocket endpoint on HTTPS port 443; use raw or websocket to force one path. quic carries the session over UDP to an edge started with -quic; it is never part of auto and never falls back.
--tokenstring
Auth token override. Defaults to NGSTONE_TOKEN or the token saved by ngstone auth.
--insecurebooldefault: false
Dial the control plane in plaintext (dev/test only, no certificates involved).
--server-namestring
TLS ServerName/SNI to verify against. Defaults to the host in the server address, so example.com:4443 verifies example.com. Ignored with --insecure.
--pinstring
Optional SPKI pin, checked in addition to normal chain validation. Off by default.
--no-tuibooldefault: false
Disable the terminal inspector UI and log plain text to stderr instead. The inspector is also skipped automatically whenever stdout isn't a terminal (piping, CI, running under &), so this flag mainly matters when stdoutis a terminal and you still want plain logs.
--basic-authstring
Require HTTP basic auth, user:pass. Repeatable for multiple valid credentials. Visible to other local users via ps//procfor the process's lifetime — prefer --basic-auth-file or NGSTONE_BASIC_AUTH. See Access control.
--basic-auth-filestring
Path to a file with one user:pass credential per line. Safer than --basic-auth.
--allow-cidrstring
Comma-separated CIDRs allowed to reach the tunnel. Empty allows any source.
--oidcbool
Require visitors to sign in with the edge's OIDC provider. See OIDC visitor login.
--oidc-allow-email, --oidc-allow-domainstring
With --oidc, allow only these verified emails or email domains. Comma-separated or repeatable.
--policy-filestring
Load a strict JSON HTTP traffic policy. Rules are evaluated in order at the edge; a denied request gets 403 and is never forwarded. Policies can also redirect, rewrite request and response headers, and answer CORS; see Traffic policies.
--ttlduration
Stop the tunnel after a positive duration such as --ttl 2h. The timer starts when the command starts.
--jsonbooldefault: false
Emit JSON Lines status events to stdout instead of opening the inspector.
--harstring
Write captured HTTP exchanges to this HAR file on exit.
--har-include-sensitivebooldefault: false
Include sensitive request and response headers in the HAR instead of redacting them.

--basic-auth takes precedence over --basic-auth-file, which takes precedence over NGSTONE_BASIC_AUTH— the first one present is used, and they don't merge. NGSTONE_BASIC_AUTH uses the same format as --basic-auth-file: one user:pass credential per line.

The native HTTP/2 path is covered by transport tests for gRPC trailers, bidirectional streaming, h2c, deadlines and cancellation, large messages, and backend connection reuse.

ngstone tcp#

Starts a raw TCP tunnel to a local port or host:port target — for SSH, Postgres, Redis, or anything else that isn't HTTP. See TCP tunnels for the full picture, including the encryption caveat.

$ ngstone tcp 22
tcp://amber-fox-42.example.com:14201 -> 127.0.0.1:22
 
$ ngstone tcp db.local:5432 --remote-port 15432

The positional argument is either a bare port number (forwarded to 127.0.0.1:<port>) or a host:port target used as-is.

--remote-port, -rintdefault: 0
Requested remote port. 0 means server-assigned.
--serverstring
Edge control-plane address override. Defaults to the config file or ngstone.site:4443.
--transportstringdefault: auto
Control transport. auto tries raw TLS first and falls back to the authenticated WebSocket endpoint on HTTPS port 443. quic needs an edge started with -quic and is never part of auto.
--tokenstring
Auth token override. Defaults to NGSTONE_TOKEN or the token saved by ngstone auth.
--insecurebooldefault: false
Dial the control plane in plaintext (dev/test only, no certificates involved).
--server-namestring
TLS ServerName/SNI to verify against. Defaults to the host in the server address, so example.com:4443 verifies example.com. Ignored with --insecure.
--pinstring
Optional SPKI pin, checked in addition to normal chain validation. Off by default.
--allow-cidrstring
Comma-separated CIDRs allowed to reach the tunnel. Empty allows any source. See Access control. There is no --basic-auth for tcp— the edge rejects it, since there's no HTTP request to attach credentials to inside a raw TCP stream.
--ttlduration
Stop the tunnel after a positive duration such as --ttl 2h.
--jsonbooldefault: false
Emit JSON Lines status events to stdout.
TCP tunnels are opt-in per edge — the operator must set -tcp-ports. See Running the edge on a VPS for how to enable it.

--allow-cidr behind a proxy needs an edge flag too

If the edge sits behind a front proxy with -proxy-protocol, --allow-cidr is only trustworthy when the edge is also started with -proxy-protocol-trusted <proxy CIDRs> — otherwise a direct client can forge a PROXY header and spoof an allowed source IP. See Behind an existing reverse proxy and Access control.

ngstone tls#

Starts a TLS passthrough tunnel: the edge routes connections by ClientHello SNI. The edge never decrypts traffic for a passthrough connection, so the local service presents its own certificate; an HTTPS request that reaches the edge's own TLS for that hostname (for example on a reused or domain-fronted connection) gets 421 and is never forwarded. See TLS passthrough.

$ ngstone tls 8443 --subdomain secure
tls://secure.example.com -> 127.0.0.1:8443

It takes the same flags as ngstone tcp, with --subdomain/-s in place of --remote-port. HTTP-only options such as --basic-auth and --host-header are not accepted.

ngstone serve#

Shares a directory of files: a built site, a folder of downloads, a report. It starts a file server on a loopback port and tunnels it exactly as ngstone port would, inspector included.

$ ngstone serve ./dist --subdomain demo
$ ngstone serve ./dist --spa
$ ngstone serve # the current directory
dirpositionaldefault: .
The directory to share. Directory listings are shown for folders without an index.html.
--spabooldefault: false
Single-page app mode: a path with no file and no extension gets index.html, so client-side routes survive a reload. Paths with an extension still return 404 when the file is missing.
--subdomain, --basic-auth, --allow-cidr, …flags
Every ngstone port flag applies.

ngstone start#

Starts every tunnel described in a tunnels file, or only the ones named on the command line, in one process. HTTP tunnels share one terminal inspector: each row shows its tunnel, the header shows one status line per tunnel, and replay goes to the app of the tunnel that captured the request.

# ngstone.yml
server: example.com:4443
tunnels:
web:
port: 3000
subdomain: demo
api:
url: http://127.0.0.1:8080
basic_auth: ["user:pass"]
allow_cidr: ["203.0.113.0/24"]
db:
kind: tcp
port: 5432
remote_port: 15432
$ ngstone start
$ ngstone start web api

HTTP tunnels take port or url, plus subdomain, host_header, basic_auth or basic_auth_file, and allow_cidr. TCP tunnels (kind: tcp) take port or address, plus remote_port and allow_cidr. Unknown keys are errors. Each tunnel is its own session, so one failing, for example on a taken subdomain, does not stop the others.

--configstring
Tunnels file. Defaults to ./ngstone.yml, then tunnels.yml in the config directory.
--serverstring
Edge control-plane address. Defaults to the file's server, then the config file, then ngstone.site:4443.
--token, --insecure, --server-name, --pinflags
As for ngstone port, applied to every tunnel. The file can also set server_name.
--no-tuibooldefault: false
Print each tunnel's URL and log plain text to stderr instead of opening the inspector.

ngstone service#

Runs ngstone start --no-tui as a background service: a systemd user unit on Linux, a launchd agent on macOS. It restarts on failure and uses the token saved by ngstone auth.

$ ngstone service install --config ~/work/ngstone.yml
$ ngstone service status
$ ngstone service uninstall
install [--config FILE] [name ...]command
Checks the tunnels file, the names and the saved token, writes the unit or plist, and starts it. A reinstall replaces and restarts it. --print shows the definition without installing.
statuscommand
Runs systemctl --user status or launchctl print for the service.
uninstallcommand
Stops the service and removes its definition.
Logs go to journalctl --user -u ngstone on Linux and ~/Library/Logs/ngstone.log on macOS. On Linux, run sudo loginctl enable-linger $USER once so the service keeps running after you log out and starts at boot.

ngstone ps#

Lists the tunnels of every ngstone process running as your user, with their state and public URL: the quick way to find the URL of a tunnel the background service started, or of a ngstone port left running in another terminal.

$ ngstone ps
PID COMMAND TUNNEL KIND STATE URL TARGET UP
41200 start web http online https://demo.example.com http://127.0.0.1:3000 1h30m
41200 start db tcp online tcp://example.com:15432 127.0.0.1:5432 1h30m
41377 port - http online https://amber-fox-42.example.com http://127.0.0.1:8080 5m
--jsonbooldefault: false
Print the raw status of each process as JSON, for scripts.

Each running process serves its status on a unix socket under $XDG_RUNTIME_DIR/ngstone/, or run/ next to the config file when that variable is unset. Sockets left by a crashed process are removed on the next ps.

ngstone share#

Shares local databases, or any TCP services, through a link that expires. Unlike tcp it opens no public port: the only way in is ngstone connect with the link. See Sharing a database.

$ ngstone share postgres --expires 2h --label "staging replica"
$ ngstone share postgres redis:6380 --approve --passphrase hunter2 --user readonly
$ ngstone share mysql db.local:3306 --allow-cidr 10.0.0.0/8 --max-uses 3
$ ngstone share tcp:9000 --single-use --idle 30m --audit-log share.jsonl

Each positional argument is a target: a preset (postgres, mysql, redis, http) with an optional :port or :host:port, or tcp:port / tcp:host:port. Connectors get one local listener per target. The older two-argument form share postgres 5433 still works for a single target. Lines typed into the sharing terminal are commands: y <id> / n <id> answer approval requests, kick <id>, extend 1h, q.

--expiresdurationdefault: 1h
Share lifetime, capped by the edge's -max-share-ttl.
--labelstring
Label shown to connectors and in listings. Defaults to the first preset.
--allow-cidrstring
Comma-separated CIDRs connectors must come from.
--max-connsintdefault: 16
Concurrent relayed connections across all connectors.
--max-connectorsintdefault: 8
Concurrent connector agents.
--max-usesintdefault: 0
How many connector agents may ever join; 0 is unlimited and 1 is the same as --single-use.
--single-usebooldefault: false
Lock the link to the first connector agent that uses it.
--idledurationdefault: 0
Close the share after this long with no open connection. Minimum 30s; 0 never.
--approvebooldefault: false
Ask in this terminal before each connector is admitted. The connector waits up to 60s for a y or n.
--passphrasestring
Require connectors to present this passphrase too. Prefer NGSTONE_SHARE_PASSPHRASE, since flags show in ps.
--userstring
Database user to put in the connection hint connectors see, for pointing them at a read-only role.
--secret-filestring
Reuse the secret stored in this file so the link stays the same across runs; created with mode 0600 if missing. NGSTONE_SHARE_SECRET also works.
--audit-logstring
Append every audit event to this file as JSON Lines.
--server, --token, --transport, --insecure, --server-name, --pinvarious
As for ngstone tcp. With --insecure the printed hint tells connectors to pass it too.

ngstone connect#

Joins a share and serves its targets on the loopback interface. Needs no token and no config file: the link carries the edge address and the secret.

$ ngstone connect ngstone://example.com:4443/s/N7kq...Vb0Q --as alice
$ ngstone connect - < link.txt
$ NGSTONE_SHARE_LINK=ngstone://... ngstone connect --port 15432 --port redis=6380
--asstring
Name the sharer sees for this connector (letters, digits, . _ -). Default c1, c2, ...; a taken name gets -2 appended.
--port, -pstring
Local port: N for the first target, or preset=N / t2=Nper target; repeatable. Default is each preset's port, or a free port when busy.
--passphrasestring
Passphrase the share requires. Prompted for when stdin is a terminal; NGSTONE_SHARE_PASSPHRASE also works.
--insecurebooldefault: false
Dial the edge in plaintext; only for links from an edge running with -insecure.
--server-namestring
TLS ServerName/SNI override. Defaults to the host in the link.
--pinstring
Optional SPKI pin, checked in addition to chain validation.
--transportstringdefault: auto
Control transport: auto, raw, websocket or quic.

Exit status is 0 on Ctrl-C, 3 when the share expired, was revoked, idled out or this connector was kicked, and 1when the link is invalid, the passphrase could not be supplied, or the share's policy or the sharer refused this connector.

ngstone shares, unshare, extend, kick#

Manage shares from any terminal that holds the token. Each opens a fresh operator session, does one thing, and exits.

$ ngstone shares # every live share, its policy and connectors
$ ngstone shares --json
$ ngstone shares --watch # every share's audit lines, live, until Ctrl-C
$ ngstone extend sh_7f3a... 2h # expire two hours from now
$ ngstone kick sh_7f3a... alice # drop one connector
$ ngstone unshare sh_7f3a... # revoke

All take --server, --token, --transport, --insecure, --server-name and --pinlike the other verbs. A revoked sharer's terminal says share revoked by another terminal and exits 0.

With several edges sharing a database, shares, extend and kick act on every edge that holds your shares, whichever edge you reach. shares adds an EDGE column and names any edge that did not answer within 3 seconds; it asks at most 32 edges. An edge running an older ngstoned answers share_not_found saying so. --watch and approvals work only on the edge holding the share.

ngstone config#

Read or change the local config file without hand-editing JSON.

$ ngstone config set server example.com:4443
server set to example.com:4443
 
$ ngstone config get
token: nst_a1b2…9f3d
server: example.com:4443
 
$ ngstone config get token
nst_a1b2…9f3d
 
$ ngstone config path
/home/you/.config/ngstone/config.json

config get always redacts the token — the middle of the value is replaced with …, only the first and last four characters are shown.

ngstone logout#

Clears the saved token from the config file. The server address is left untouched.

$ ngstone logout
logged out

ngstone version#

Prints the build's version string, injected at compile time via -ldflags.

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

No arguments and -h#

Running ngstone with no arguments does not start a tunnel — it prints usage to stderr and exits 1. -h, --help, and -help print the same usage to stdout and exit 0.

Scoped credentials & legacy token#

The preferred path is ngstone credentials issue. It creates a short-lived credential scoped to one HTTP or TLS subdomain or TCP port, stores only its hash, and prints the plaintext once:

$ ngstone credentials issue --file /var/lib/ngstoned/credentials.json --subdomain demo --ttl 24h
$ ngstone auth '<token printed once>'

Legacy shared-token mode

The shared-token one-liner remains for older edges. The edge only ever stores the token's SHA-256 hash, but one token can bind any non-denylisted subdomain and cannot be revoked independently.
TOKEN=$(openssl rand -base64 32 | tr '+/' '-_' | tr -d '=')
HASH=$(printf '%s' "$TOKEN" | shasum -a 256 | cut -d' ' -f1) # sha256sum on Linux

Keep $TOKEN for ngstone auth on every machine that will run the agent, and pass $HASH to the edge as -token-sha256 (or $NGSTONE_TOKEN_SHA256) only for legacy deployments. Prefer one scoped credential per tunnel so expiry and revocation do not affect unrelated agents.

The config file#

ngstone auth, ngstone up, ngstone port, ngstone config, and ngstone logout all use the saved credential JSON file:

$XDG_CONFIG_HOME/ngstone/config.json
# falls back to ~/.config/ngstone/config.json if XDG_CONFIG_HOME is unset

The file holds token and server. It's written with mode 0600 inside a 0700 directory, and saved via a temp-file-plus-rename so a crash mid-write can't corrupt it.

ngstone up reads tunnel definitions from its separate project file, described in ngstone up; project configuration does not belong in this credential file.

Resolution order for both the token and the server address:

1. Flaghighest precedence
--token / --server on the command invoking it.
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.

Legacy flag form#

A flat-flags invocation is still supported alongside the verbs above, mainly for scripts and the e2e test suite written against it. It starts a tunnel directly — there's no config file involved.

$ ngstone -control ADDR -token TOK -target URL -subdomain NAME \
-insecure -server-name NAME -pin SPKI -instance-id ID
-controlstringdefault: ngstone.site:4443
Edge control-plane address.
-tokenstring
Auth token. Falls back to NGSTONE_TOKEN if unset.
-targetstringdefault: http://127.0.0.1:3000
Local target URL to forward requests to.
-subdomainstring
Requested subdomain. Empty means server-assigned.
-instance-idstring
Undocumented, testing-only: force a specific instance ID instead of generating one.
-insecurebooldefault: false
Dial the control plane in plaintext (dev/test only).
-server-namestring
TLS ServerName/SNI to verify against. Defaults to the host part of -control.
-pinstring
Optional SPKI pin.
-versionbooldefault: false
Print version and exit.

Prefer ngstone auth plus ngstone port for day-to-day use — the legacy form exists for compatibility, not as the recommended path.