Quick Start Guide

Get up and running with NGSRV in under 5 minutes

1Install the CLI

Pick the install path that matches your OS. Every channel tracks the same release artifacts, so you'll always end up on the latest version.

macOS — Homebrew (recommended)

brew install ngsrv/tap/ngsrv

The ngsrv/homebrew-tap repository is auto-updated on every CLI release, so brew upgrade ngsrv always lands on the latest version.

macOS / Linux — curl

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

Docker

docker pull ngsrv/cli:latest

Multi-arch image (linux/amd64, linux/arm64, linux/arm/v7). An alpine variant is also published as ngsrv/cli:alpine.

The curl and PowerShell installers automatically add NGSRV to your PATH. You may need to restart your terminal afterward.

Verify installation: Run ngsrv version

2Create an API Token

Generate an API token to authenticate your CLI:

Log into your Dashboard
Navigate to API Tokens in the sidebar
Click "Create Token" button
Give it a descriptive name (e.g., "My Laptop", "CI/CD")

Important: Store your token securely. Treat it like a password!

Authenticate your CLI with the token:

ngsrv token YOUR_API_TOKEN_HERE

The token is stored securely in ~/.ngsrv/tokens.json

Create API Token

3Start Your First Tunnel

Expose your local application to the internet:

Basic tunnel:

ngsrv http 3000

Creates a tunnel to localhost:3000 with a random subdomain

With custom domain:

ngsrv http 3000 --domain myapp

Uses your custom domain: myapp.tnl.ngsrv.com

With security policies:

ngsrv http 3000 --policy ngsrv_ips_ABC123

Applies IP security or other policies (create them in Dashboard first)

What happens next:

✓ CLI connects to NGSRV servers
✓ You receive a public HTTPS URL
✓ Local dashboard available at localhost:4040
✓ All traffic is securely forwarded to your local port

4Test Your Tunnel

Verify your tunnel is working:

Copy the public URL from the CLI output
Open it in your browser or send a request with curl
You should see your local application!
Visit localhost:4040 to see real-time request logs
Check the Tunnels page in your dashboard for analytics

# Test with curl:

curl https://your-subdomain.tnl.ngsrv.com

5Explore Advanced Features

Now that you have a tunnel running, explore these powerful features:

Security Policies

Protect tunnels with IP whitelisting, geo-restrictions, WAF rules, and more

Custom Domains

Create persistent subdomains for consistent URLs across sessions

Analytics

Monitor traffic, bandwidth, and request logs in real-time

Team Collaboration

Share domains, policies, and resources with your team

CLI Commands Quick Reference

Command	Description	Example
ngsrv http	Create HTTP tunnel	ngsrv http 3000
ngsrv tcp	Create TCP tunnel	ngsrv tcp 4500
ngsrv serve	Share files/directories	ngsrv serve ./public
ngsrv domain list	List your domains	ngsrv domain list
ngsrv domain create <name>	Reserve a subdomain on your team's base domain	ngsrv domain create myapp

Common Flags:

--domain, -d - Custom domain

--policy, -p - Apply security policy

--force, -f - Force create (terminate existing)

--list, -l - List active tunnels

Troubleshooting Common Issues

Error: "Not authenticated"

Solution: Run ngsrv token YOUR_TOKEN or set NGSRV_API_TOKEN environment variable.

Error: "Invalid JWT"

Solution: Your token may be expired or invalid. Create a new token in the dashboard.

Error: "Port already in use"

Solution: Another process is using that port. Either stop it or choose a different port.

Error: "Domain not found"

Solution: Check available domains with ngsrv domain list or create a new one with ngsrv domain create NAME.

Tunnel connects but shows 502 Bad Gateway

Solution: Your local server isn't running or isn't listening on the specified port. Start your application first, then create the tunnel.

Common causes:

Service stopped or crashed after tunnel started
Service bound to wrong interface (must listen on 127.0.0.1 or 0.0.0.0)
Wrong port number specified
Firewall blocking localhost connections

Quick fix: Test locally with curl http://localhost:PORT before creating the tunnel.

Error: "No connection could be made because the target machine actively refused it"

Solution: This means your local service isn't running or isn't accessible on localhost. The CLI now checks this before starting, but if you see this error:

Verify your service is running: curl http://localhost:PORT
Check the service is bound to 127.0.0.1 or 0.0.0.0 (not just external IP)
Restart your service and try again
On Windows, check Windows Firewall isn't blocking localhost

Request blocked by security policy

Solution: Check audit logs to see which policy blocked it and adjust the configuration accordingly.

Need more help?

Check the full documentation or contact support through the dashboard.