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.

Project (ngstone up)#

ngstone up starts several tunnels from a checked-in JSON project file. It searches the current directory for ngstone.json, then .ngstone.json; use --file to select another path.

{
"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
},
"database": {
"kind": "tcp",
"target": "5432",
"remote_port": 15432
}
}
}
tunnelsobjectrequired
Map of stable tunnel names to definitions. Names may contain letters, numbers, -, _, and ..
kindstringdefault: http
http, tcp, or tls. A tls tunnel is routed by SNI and passed through without decryption; see TLS passthrough. It accepts subdomain and allow_cidr, and rejects the HTTP-only fields and remote_port.
targetstringrequired
Bare local port, host:port for TCP or TLS, or a full HTTP URL.
subdomainstring
Requested public subdomain.
host_headerstring
HTTP-only Host header for the local app. For example, set it to demo.localhost:3000 for a tenant-aware local app.
http2booldefault: false
HTTP-only. Forward the tunnel over native HTTP/2. An https:// target uses TLS HTTP/2; an http:// target uses cleartext h2c. Enable this for native gRPC, trailers, streaming, and full-duplex requests.
multi_connectorbooldefault: false
HTTP-only. Allow multiple agent processes to share the same named subdomain and load-balance requests across healthy connectors. Every connector must use the same setting and public subdomain; a connector must reconnect or drain independently.
connector_token_envstringdefault: NGSTONE_CONNECTOR_TOKEN
Environment variable name containing the per-tunnel connector secret for multi_connector mode. The project file stores only the variable name, never the secret itself.
credential_envstring
Environment variable containing this tunnel's scoped edge credential. The project file stores only the variable name, never the token itself. If unset, NGSTONE_TOKEN or the saved config token is used.
remote_portintdefault: 0
TCP-only requested public port; 0 means assigned.
ttlduration
Positive duration such as 2h. The tunnel stops when the duration from process start expires.
server, server_name, pinstring
Per-tunnel control-plane and TLS overrides.
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.
insecurebooldefault: false
Disable TLS for development and testing only.
basic_auth_filestring
HTTP-only path to one user:pass credential per line. Relative paths are resolved from the project file directory.
allow_cidrstring
Comma-separated source CIDRs allowed by the edge.
policy_filestring
HTTP-only path to a strict JSON traffic policy. Relative paths are resolved from the project file directory; rules are evaluated in order at the edge.

The project format is strict JSON: unknown fields fail fast. It never accepts token; ngstone up resolves the token from NGSTONE_TOKEN or the saved credential file, just like ngstone port. Keep credential files out of source control, and protect any basic_auth_file with mode 0600.

Edge (ngstoned)#

-domainstringrequired
Base domain used to build tunnel hostnames and the two managed certificates, for example example.com. There is no default.
-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.
-admin-token-sha256string
Hex-encoded SHA-256 of the management API bearer token. When unset,/api/v1 accepts only loopback requests. Defaults to $NGSTONE_ADMIN_TOKEN_SHA256. Store only the hash on the edge and keep the plaintext token with the operator.
-oidc-issuer, -oidc-client-idstring
OIDC issuer and client ID. These enable browser management login; client secret and cookie secret are read only from NGSTONE_OIDC_CLIENT_SECRET and NGSTONE_OIDC_COOKIE_SECRET.
-oidc-redirect-urlstring
Exact HTTPS callback registered with the OIDC provider, normally https://edge.example.com:4041/api/v1/auth/oidc/callback.
-oidc-admin-groups, -oidc-operator-groups, -oidc-viewer-groupsstring
Comma-separated IdP groups mapped to the admin, operator, and viewer roles. A user must match a group unless -oidc-default-role is set.
-oidc-groups-claimstringdefault: groups
Userinfo claim containing team/group names.
-oidc-allowed-email-domainsstring
Optional comma-separated email domain allow-list.
-oidc-default-rolestring
Optional fallback role for an authenticated user with no matching group. Empty by default, which is the least-privilege setting.
-public-schemestringdefault: https
Scheme advertised in BindOK.URL — http or https.
-credentials-filepath
Legacy versioned per-tunnel credential file. The durable database backend is preferred for new deployments. Defaults to $NGSTONE_CREDENTIALS_FILE.
-database-urlstring
Durable control-plane database URL. Defaults to $NGSTONE_DATABASE_URL or SQLite at /var/lib/ngstoned/control.db when no legacy credential source is configured. Use a PostgreSQL URL for multiple edge servers.
-database-driverstring
Optional sqlite or postgres override. The driver is inferred from the database URL when omitted.
-edge-idstring
Stable identity for this edge process in connector leases and audit events. Defaults to $NGSTONE_EDGE_ID or a generated ID.
-lease-ttldurationdefault: 45s
Connector lease lifetime. Heartbeats renew it while a connector is healthy; an expired lease can be reclaimed by another edge.
-token-sha256string
Legacy hex-encoded SHA-256 of the shared auth token. Used only when-credentials-file and $NGSTONE_CREDENTIALS_FILE are unset. 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.
-custom-certsstring
Optional. Operator certificates for active custom domains; they take precedence over certificates the edge obtains automatically. Directory of <name>.crt and <name>.key pairs served for active custom domains. Keys must be mode 0600. Needs durable storage and a TLS public listener. Read at start-up, so changes need a restart; an expired or unreadable pair stops the edge. Also $NGSTONE_CUSTOM_CERTS_DIR.
-dns-providerstringdefault: cloudflare
DNS provider used for the DNS-01 certificate challenges: cloudflare, route53, digitalocean, hetzner, vultr, ovh, desec, or bunny. Its credentials are read from the environment only — see below. -dns-provider help prints the providers and the variables each reads, then exits.
-cf-api-tokenstring
Legacy flag for the Cloudflare API token, used only with -dns-provider cloudflare when $NGSTONE_CF_API_TOKEN is unset. Prefer the environment variable.

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, -upgrade-inflight, -per-session-upgrade, -handshake-concurrency, -unauth-sessions, -unauth-per-addr, -per-ip-inflight, -client-idle-timeout, -tcp-idle-timeout, -webhook-max-body-bytes, -webhook-buffer-bytes, -max-share-ttl, -share-audit-log). See Limits & timeouts for the full set and their defaults.

Environment variables#

NGSTONE_TOKENagent env
Fallback token source for ngstone port, tcp, and up, below a --token flag where one exists and above the saved config file.
NGSTONE_ADMIN_SERVERadmin CLI env
Default management API URL for ngstone admin. It defaults to http://127.0.0.1:4041.
NGSTONE_ADMIN_TOKENadmin CLI env
Bearer token for ngstone admin. Prefer this environment variable to --token so the secret is not visible in process listings.
NGSTONE_OIDC_ISSUER, NGSTONE_OIDC_CLIENT_IDedge env
OIDC provider issuer and client ID. Setting any OIDC value activates validation of the complete browser-login configuration.
NGSTONE_OIDC_CLIENT_SECRET, NGSTONE_OIDC_COOKIE_SECRETedge env
OIDC client secret and at least 32 bytes of random cookie-encryption secret. These values have no command-line flag and must stay in the root-only environment file.
NGSTONE_OIDC_REDIRECT_URLedge env
Exact callback URL registered at the provider.
NGSTONE_OIDC_GROUPS_CLAIM, NGSTONE_OIDC_ADMIN_GROUPS, NGSTONE_OIDC_OPERATOR_GROUPS, NGSTONE_OIDC_VIEWER_GROUPSedge env
Group claim and comma-separated role mappings. Admin wins over operator, which wins over viewer.
NGSTONE_OIDC_ALLOWED_EMAIL_DOMAINS, NGSTONE_OIDC_DEFAULT_ROLEedge env
Optional email-domain allow-list and fallback role. The fallback is empty by default, so an unmapped IdP user is rejected.
NGSTONE_TOKEN_SHA256edge env
Legacy shared-token hash. Prefer NGSTONE_CREDENTIALS_FILE.
NGSTONE_CREDENTIALS_FILEedge env
Compatibility path to the scoped credential file. Use the durable database backend for new deployments.
NGSTONE_CUSTOM_CERTS_DIRedge env
Directory for -custom-certs; the environment value wins over the flag.
NGSTONE_DATABASE_URLedge env
Durable SQLite or PostgreSQL URL. SQLite is the default when neither this variable nor a legacy credential source is set.
NGSTONE_DATABASE_DRIVERedge env
Optional database driver override: sqlite or postgres.
NGSTONE_EDGE_IDedge env
Stable edge identity used for leases and audit records.
NGSTONE_CF_API_TOKENedge env
-dns-provider cloudflare: API token with Zone / DNS / Edit on the zone only. Preferred over -cf-api-token.
NGSTONE_AWS_REGION, NGSTONE_AWS_ACCESS_KEY_ID, NGSTONE_AWS_SECRET_ACCESS_KEYedge env
-dns-provider route53: region and the keys of an IAM user allowed route53:ListHostedZonesByName, ListResourceRecordSets, ChangeResourceRecordSets, and GetChange.
NGSTONE_DO_API_TOKENedge env
-dns-provider digitalocean: personal access token with domain read and write.
NGSTONE_HETZNER_API_TOKENedge env
-dns-provider hetzner: read and write API token of the Hetzner Console project holding the zone. Zones on the deprecated dns.hetzner.com must be migrated first.
NGSTONE_VULTR_API_KEYedge env
-dns-provider vultr: API key, with the VPS's IP allowed in its access control.
NGSTONE_OVH_ENDPOINT, NGSTONE_OVH_APPLICATION_KEY, NGSTONE_OVH_APPLICATION_SECRET, NGSTONE_OVH_CONSUMER_KEYedge env
-dns-provider ovh: endpoint ovh-eu, ovh-ca, or ovh-us, plus a consumer key limited to GET, POST, and DELETE on /domain/zone/*.
NGSTONE_DESEC_TOKENedge env
-dns-provider desec: API token. deSEC's 3600 s minimum TTL and rate limits can make issuance take a few minutes.
NGSTONE_BUNNY_API_KEYedge env
-dns-provider bunny: account API key.
NGSTONE_ADMIN_TOKEN_SHA256edge env
SHA-256 hash of the management API bearer token. It enables bearer authentication for /api/v1; without it, that API is loopback-only. Prefer this environment variable to the equivalent command-line flag.
-alert-webhookstring
HTTP(S) webhook for connector, lease, and credential lifecycle events. Defaults to $NGSTONE_ALERT_WEBHOOK_URL. The optional NGSTONE_ALERT_WEBHOOK_TOKEN is sent as a bearer header.

Only providers whose libdnsmodule adds and removes individual TXT values are supported, because the apex and wildcard certificates publish challenges at the same name concurrently. GoDaddy, Namecheap, Porkbun, IONOS, Azure, DNSimple, and netcup are not; move the zone's DNS hosting to a supported provider instead. See Choosing a DNS provider.

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. DNS provider credentials other than Cloudflare come from the environment only.

On the agent, resolving the token or server address for direct tunnel commands and ngstone up follows this chain:

1. Flaghighest precedence
--token / --server.
2. Environmenttoken only
credential_env for a project tunnel, otherwise 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.