Configuration Files

Define default settings for your tunnels with ngsrv.yml

Overview

Configuration files let you define default tunnel settings per project. Create a ngsrv.yml file in your project root to avoid repeating flags every time.

Benefits

• Consistent tunnel configuration across your team
• No need to remember complex commands
• Version control your tunnel settings
• Environment-specific configurations

Basic Configuration

Create ngsrv.yml in your project root:

# ngsrv.yml
port: 3000
domain: myapp

Now simply run ngsrv http and it will use these settings!

Configuration Schema

All available configuration options:

# ngsrv.yml - Complete Configuration

# Required: Local port to tunnel
port: 3000

# Optional: Local host (defaults to localhost)
# Use this when the local app listens on a non-loopback interface,
# e.g. inside a docker network ("app", "host.docker.internal", etc).
host: localhost

# Optional: Domain to use. Pick ONE of the two:
#   - subdomain: a reserved short name on the team's tnl.ngsrv.com space
#     (e.g. subdomain: myapp -> myapp.tnl.ngsrv.com)
#   - domain:    a full FQDN that you've added & verified as BYOD
#     (e.g. domain: api.example.com)
subdomain: myapp
# domain: api.example.com

# Optional: Security policy IDs to apply (array of policy IDs from the
# dashboard at /dashboard/security). Examples:
security_policies:
  - ngsrv_ips_ABC123     # IP whitelist
  - ngsrv_time_DEF456    # Time-based access
  - ngsrv_hdr_GHI789     # Header authentication

# Optional: Preferred edge region (advisory; routing falls back as needed)
region: us-central1

Notes:

CLI flags always override config file values (--domain, --policy, etc.).
The CLI auto-loads ngsrv.yml or ngsrv.yaml from the current working directory. Override with --config <path>.
config: is not a config-file key. It is the --config CLI flag only.
ngsrv http, ngsrv tcp, and ngsrv serve all read this file.

Multi-tunnel form (CLI v2.3.0+)

For sidecar deployments declare every tunnel under a top-level tunnels: array and run them all from one process with ngsrv run.

# ngsrv.yml (multi-tunnel form)
tunnels:
  - name: web
    port: 3000
    subdomain: web
  - name: api
    port: 8080
    subdomain: api
    security_policies:
      - ngsrv_ips_office

Configuration Examples

Next.js Development

# ngsrv.yml
port: 3000
domain: myapp-nextjs
security_policies:
  - ngsrv_ips_office  # Only accessible from office

Laravel API with Webhooks

# ngsrv.yml
port: 8000
domain: myapp-api
security_policies:
  - ngsrv_rate_limit_standard  # Protect against abuse
  - ngsrv_waf_basic           # Basic WAF protection

Django with Team Access

# ngsrv.yml
port: 8000
domain: myapp-staging
security_policies:
  - ngsrv_ips_team         # Team IPs only
  - ngsrv_time_business    # Business hours only
  - ngsrv_auth_basic       # Require password

React Frontend (Simple)

# ngsrv.yml
port: 5173
domain: myapp-frontend

Production-like Setup (Maximum Security)

# ngsrv.yml
port: 8080
domain: myapp-prod-test
security_policies:
  - ngsrv_ips_whitelist       # Only known IPs
  - ngsrv_geo_usa_only        # US traffic only
  - ngsrv_rate_strict         # Strict rate limits
  - ngsrv_waf_full            # Full WAF protection
  - ngsrv_mtls_enterprise     # Client certificates required

Multiple Environment Configs

Use different config files for different environments:

File Structure

project/

├── ngsrv.yml (default/development)

├── ngsrv.staging.yml

└── ngsrv.production.yml

Usage

# Development (default)

ngsrv http

# Staging

ngsrv http --config ngsrv.staging.yml

# Production test

ngsrv http --config ngsrv.production.yml

Environment Variables

The CLI reads the following environment variables. Authentication is handled by ngsrv token <value>, which writes to ~/.ngsrv/tokens.json. Containers and CI runners that don't ship a tokens file can instead set NGSRV_API_TOKEN (CLI v2.2.9+) and the CLI will use that value when no token file is present.

Variable	Default	Description
NGSRV_API_TOKEN	unset	Token used when `~/.ngsrv/tokens.json` is missing. Must start with `ngsrv_`. Recommended for Docker, k8s sidecars, and CI.
NGSRV_LOG_FORMAT	text	`text` or `json`. Same as the persistent `--log-format` flag. JSON is the right pick for log scrapers.
NGSRV_LOG_LEVEL	info	`debug` \| `info` \| `warn` \| `error`. Same as `--log-level`.
NGSRV_OPS_PORT	unset	Port for `/healthz`, `/readyz`, `/metrics`. Same as `--ops-port`. Required for k8s probes.
NGSRV_NO_TUI	unset	Set to a non-zero value to disable the interactive TUI. The CLI also auto-disables the TUI whenever stdout is not a terminal or `--log-format json` is set.
NGSRV_CLIENT_TRACE	unset	Verbose connection / request logging. Set to any non-empty value (other than `0`) to enable. Equivalent to passing `--trace`.
NGSRV_KEEPALIVE_SEC	30	WebSocket heartbeat interval (seconds).
NGSRV_RECONNECT_BASE_MS	500	Initial backoff (ms) for reconnect attempts.
NGSRV_RECONNECT_MAX_SEC	30	Maximum backoff (seconds) for reconnect attempts.
NGSRV_TEST_DOMAIN	unset	Internal: override the resolved tunnel hostname for QA.
NGSRV_WS_URL	unset	Internal: override the WebSocket endpoint URL for QA.

Example Usage

# Authenticate the CLI (one time)

ngsrv token ngsrv_your_token_here

# Verbose mode for debugging a single run

NGSRV_CLIENT_TRACE=1 ngsrv http 3000

# Slower keepalive on flaky networks

NGSRV_KEEPALIVE_SEC=15 ngsrv http 3000

CI/CD Configuration

Use config files in your CI/CD pipelines:

GitHub Actions Example

# .github/workflows/test.yml
name: Test with NGSRV

on: [pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Install NGSRV
        run: curl -fsSL https://get.ngsrv.com | bash
      
      - name: Start tunnel
        env:
          NGSRV_API_TOKEN: ${{ secrets.NGSRV_TOKEN }}
        run: |
          ngsrv http --config ngsrv.ci.yml &
          sleep 3
      
      - name: Run tests
        run: npm test

Best Practices

✅ Version Control

Commit ngsrv.yml to your repository so team members have the same configuration.

✅ Document Policy IDs

Add comments explaining which security policies are applied and why.

❌ Don't Commit Tokens

Never include API tokens in config files. Use environment variables or CI secrets.

💡 Per-Developer Domains

Each team member can override the domain locally without changing the config file.

Next Steps

→ Learn about HTTP tunnel options → Create custom domains → Configure security policies → Use in CI/CD pipelines