ngsrv

NGSRV Documentation

A secure, fast tunneling service for exposing local servers to the internet. Perfect for development, testing webhooks, and team collaboration.

Quick Start

Get up and running in under 5 minutes

Start now

Security Policies

Protect your tunnels with 7 policy types

Explore

DevOps Guide

Integrate into CI/CD pipelines

Learn more

Getting Started

Installation

Install the NGSRV CLI using our installation script:

macOS / Linux:

curl -fsSL https://get.ngsrv.com | bash

Windows (PowerShell):

irm https://get.ngsrv.com/windows | iex

Windows (CMD):

curl -fsSL https://get.ngsrv.com/install.bat -o install.bat && install.bat

The installer automatically adds NGSRV to your PATH.

Authentication

Create an API token and authenticate your CLI:

  1. Go to Dashboard → API Tokens
  2. Click "Create Token" and give it a name
  3. Authenticate your CLI:
ngsrv token YOUR_API_TOKEN

Or set an environment variable:

export NGSRV_API_TOKEN=your_token_here

Create Your First Tunnel

Expose your local HTTP server to the internet:

Basic tunnel:

ngsrv http 3000

With custom domain:

ngsrv http 3000 --domain myapp

With security policies:

ngsrv http 3000 --policy ngsrv_ips_ABC123 --policy ngsrv_geo_XYZ789

You'll receive a public HTTPS URL like https://abc123.tnl.ngsrv.com

Share Files & Directories

Serve local files over HTTPS:

Serve current directory:

ngsrv serve

Serve specific folder:

ngsrv serve ./public

Configuration Files

Create a ngsrv.yml file in your project root to define default settings:

# ngsrv.yml
port: 3000
domain: myapp
security_policies:
  - ngsrv_ips_ABC123
  - ngsrv_time_DEF456

Now just run ngsrv http and it will use your config!

CLI Commands Reference

CommandDescription
ngsrv http <port>Create HTTP tunnel
ngsrv tcp <port>Create TCP tunnel (allocated port or BYOD on :443)
ngsrv serve [dir]Share files/directories
ngsrv domain listList your domains
ngsrv domain create <name>Create custom domain
ngsrv domain set-default <name>Set default domain (local CLI preference)
ngsrv token <token>Authenticate CLI
ngsrv versionShow CLI version

Common Flags:

  • --domain, -d - Use specific domain
  • --policy, -p - Apply security policy (can use multiple times)
  • --config, -c - Path to config file
  • --force, -f - Force create tunnel (terminate existing)
  • --list, -l - List active tunnels

Security Policies

Protect your tunnels with comprehensive security policies. All policies are managed in the Dashboard.

IP Security

Whitelist/blacklist IP addresses and CIDR ranges. Perfect for restricting access to office networks or VPNs.

Configure →

Geographic Restrictions

Allow or block traffic from specific countries. Essential for GDPR compliance and regional restrictions.

Configure →

Header Authentication

Require HTTP Basic Auth or custom headers. Great for protecting internal tools and APIs.

Configure →

Time-Based Access

Allow or block access during specific days and times. Perfect for business hours restrictions.

Configure →

Rate Limiting

Limit requests per IP or globally. Protect against abuse and DoS attacks.

Configure →

WAF Rules

Web Application Firewall with SQL injection, XSS, and custom pattern detection.

Configure →

Team Management

Collaborate with your team by sharing domains, policies, and tunnels. All resources belong to teams, not individual users.

How Teams Work

  • • Every user has a personal team (created automatically)
  • • Team owners can invite members via email
  • • All domains, policies, and API tokens are team-scoped
  • • Members can create tunnels using team resources
  • • Billing and usage are tracked per team
Manage Team →

Full Capture Consent (Paid Feature)

By default, NGSRV logs minimal request data (method, path, status, timing). Paid teams can opt-in to Full Capture mode to log complete request/response bodies for debugging.

This is a team-wide setting that requires explicit consent and is only available on Pro or Pay-as-you-go plans.

Configure Full Capture →

Analytics & Monitoring

Monitor your tunnels with real-time analytics and request logs.

Global Analytics

View aggregated metrics across all your tunnels: requests, bandwidth, active tunnels, and per-minute breakdowns.

View Analytics →

Request Logs

Inspect individual HTTP requests with method, path, status, headers, and timing. Full bodies available with Full Capture mode.

View Logs →

Audit Logs

Track all security policy actions (blocked/allowed requests) with timestamps, IPs, and reasons.

View Audit Logs →

CLI Dashboard

When running a tunnel, visit localhost:4040 for real-time local analytics.

Troubleshooting

Common Issues

❌ "Not authenticated" error

Run ngsrv token YOUR_TOKEN or set NGSRV_API_TOKEN environment variable.

❌ "Invalid JWT" error

Your API token may be expired. Create a new one in the dashboard.

❌ "Domain not found" error

Check domain name with ngsrv domain list or create a new one.

❌ Tunnel blocked by security policy

Check audit logs in dashboard to see which policy blocked the request and adjust configuration.

❌ Port already in use

Another process is using that port. Stop it or choose a different port.

Next Steps