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 versionngstone 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 savedngstone.site:4443 if neither is set.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.ServerName/SNI to verify against. Defaults to the host in the server address, so example.com:4443 verifies example.com. Ignored with --insecure.--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:4443verified against example.com:4443 and savedA 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:4041Open this URL in your browser to sign in with OIDC:https://edge.example.com:4041/api/v1/auth/oidc/start$ ngstone admin login --jsonNGSTONE_ADMIN_SERVER orhttp://127.0.0.1:4041.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 --jsonngstone.site:4443.NGSTONE_TOKEN or the saved agent config.auto, raw, websocket, or quic.--insecure is explicitly set.NGSTONE_ADMIN_TOKEN.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 24hcredential 7109b9faf3f8b5d38086d3e0566c1296 issuedtoken: nst_...$ ngstone credentials list --file /var/lib/ngstoned/credentials.json$ ngstone credentials revoke 7109b9faf3f8b5d38086d3e0566c1296 --file /var/lib/ngstoned/credentials.json--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.--json for machine-readable metadata.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 demoOperator 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 demoSuccessful 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/statusGET /api/v1/tunnelsGET /api/v1/credentialsPOST /api/v1/credentialsDELETE /api/v1/credentials/{id}GET /api/v1/policiesPOST /api/v1/policiesDELETE /api/v1/policies/{id}GET /api/v1/domainsPOST /api/v1/domainsDELETE /api/v1/domains/{id}POST /api/v1/domains/{id}/statusPOST /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>"}}--json for dashboards and automation.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.--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.NGSTONE_ADMIN_SERVER orhttp://127.0.0.1:4041.NGSTONE_ADMIN_TOKEN; prefer the environment so it does not appear in process listings.Keep the ops listener private
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 upweb: https://demo.ngstone.site -> http://127.0.0.1:3000api: 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"}ngstone.json or .ngstone.json in the current directory.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-tui30m to shorten it.expires_at.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
--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--curl is used; with --curl --target, the original host is preserved in the generated command.--curl output. Redaction is the default.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-connectorThe 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 demo for demo.ngstone.site.--host-header demo.localhost:3000.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.--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.NGSTONE_CONNECTOR_TOKEN so the secret is not exposed in the process command line.ngstone.site:4443.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.NGSTONE_TOKEN or the token saved by ngstone auth.ServerName/SNI to verify against. Defaults to the host in the server address, so example.com:4443 verifies example.com. Ignored with --insecure.&), so this flag mainly matters when stdoutis a terminal and you still want plain logs.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.user:pass credential per line. Safer than --basic-auth.--oidc, allow only these verified emails or email domains. Comma-separated or repeatable.403 and is never forwarded. Policies can also redirect, rewrite request and response headers, and answer CORS; see Traffic policies.--ttl 2h. The timer starts when the command starts.--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 22tcp://amber-fox-42.example.com:14201 -> 127.0.0.1:22 $ ngstone tcp db.local:5432 --remote-port 15432The positional argument is either a bare port number (forwarded to 127.0.0.1:<port>) or a host:port target used as-is.
0 means server-assigned.ngstone.site:4443.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.NGSTONE_TOKEN or the token saved by ngstone auth.ServerName/SNI to verify against. Defaults to the host in the server address, so example.com:4443 verifies example.com. Ignored with --insecure.--basic-auth for tcp— the edge rejects it, since there's no HTTP request to attach credentials to inside a raw TCP stream.--ttl 2h.-tcp-ports. See Running the edge on a VPS for how to enable it.--allow-cidr behind a proxy needs an edge flag too
-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 securetls://secure.example.com -> 127.0.0.1:8443It 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 directoryindex.html.index.html, so client-side routes survive a reload. Paths with an extension still return 404 when the file is missing.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.ymlserver: example.com:4443tunnels: 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 apiHTTP 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.
./ngstone.yml, then tunnels.yml in the config directory.server, then the config file, then ngstone.site:4443.ngstone port, applied to every tunnel. The file can also set server_name.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--print shows the definition without installing.systemctl --user status or launchctl print for the service.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 psPID COMMAND TUNNEL KIND STATE URL TARGET UP41200 start web http online https://demo.example.com http://127.0.0.1:3000 1h30m41200 start db tcp online tcp://example.com:15432 127.0.0.1:5432 1h30m41377 port - http online https://amber-fox-42.example.com http://127.0.0.1:8080 5mEach 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.jsonlEach 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.
-max-share-ttl.0 is unlimited and 1 is the same as --single-use.0 never.y or n.NGSTONE_SHARE_PASSPHRASE, since flags show in ps.NGSTONE_SHARE_SECRET also works.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. _ -). Default c1, c2, ...; a taken name gets -2 appended.N for the first target, or preset=N / t2=Nper target; repeatable. Default is each preset's port, or a free port when busy.NGSTONE_SHARE_PASSPHRASE also works.-insecure.ServerName/SNI override. Defaults to the host in the link.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... # revokeAll 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:4443server set to example.com:4443 $ ngstone config gettoken: nst_a1b2…9f3dserver: example.com:4443 $ ngstone config get tokennst_a1b2…9f3d $ ngstone config path/home/you/.config/ngstone/config.jsonconfig 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 logoutlogged outngstone version#
Prints the build's version string, injected at compile time via -ldflags.
$ ngstone versionngstone 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
TOKEN=$(openssl rand -base64 32 | tr '+/' '-_' | tr -d '=')HASH=$(printf '%s' "$TOKEN" | shasum -a 256 | cut -d' ' -f1) # sha256sum on LinuxKeep $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 unsetThe 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:
--token / --server on the command invoking it.NGSTONE_TOKEN. There is no environment override for the server address.ngstone auth or ngstone config set last saved.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 IDNGSTONE_TOKEN if unset.-control.Prefer ngstone auth plus ngstone port for day-to-day use — the legacy form exists for compatibility, not as the recommended path.