ngsrv run
Run one or more tunnels declared in ngsrv.yml from a single process. The recommended entrypoint for sidecar deployments. Available in CLI v2.3.0+.
Synopsis
ngsrv run [--config <path>] [--ops-port <port>] [--log-format text|json] [--log-level debug|info|warn|error] [--quiet] [--trace]
When --config is omitted, the CLI looks for ./ngsrv.yml (or ./ngsrv.yaml) in the current working directory. The file may declare a single tunnel (legacy form) or many under tunnels:.
Multi-tunnel example
# ngsrv.yml
tunnels:
- name: web
port: 3000
host: localhost # default
subdomain: web
- name: api
port: 8080
subdomain: api
security_policies:
- ngsrv_ips_office # apply your saved IP allow-list
- name: grpc
port: 9000
subdomain: grpcEach entry accepts the same keys as a single-tunnel ngsrv.yml (see the config reference): port, host, subdomain, domain, security_policies, region. The name field is operator-friendly metadata used in logs.
$ ngsrv run --log-format json --ops-port 9091
Authenticate the same way as every other command: write ~/.ngsrv/tokens.json with ngsrv token, or set NGSRV_API_TOKEN in the environment (containers, CI).
Operational behaviour
- Aggregated readiness.
/readyzreturns 200 only when every declared tunnel is connected and registered. Any single tunnel failing makes the Pod unready and Kubernetes routes traffic away. - Aggregated metrics.
/metricssums per-tunnel counters into one Prometheus exposition. Per-tunnel state changes are emitted as structured log events with atunnelattribute so log queries can group by name. - Fail-fast. If any tunnel exits with an error, the whole process exits with the matching exit code so the supervisor (Kubernetes, systemd, Compose) restarts the pod cleanly. SIGTERM stops every tunnel cooperatively.
- Single shared signal handler.
SIGINT/SIGTERMdrains all tunnels before exiting with code 0.