Getting Started — Docs

Quickstart

Create a secure, public URL to your local app in under 60 seconds.

1. Install the agent

Pick your platform on the right and run the install command.

2. Authenticate

Save your API token to authenticate the agent. Tokens are generated from the dashboard.

Tip: Tokens are scoped and revocable from the dashboard at any time.

3. Launch your first endpoint

Share your local app on port 3000 with a predictable subdomain.

Next: Open the Inspector to live-tail and replay webhooks.

Install (macOS)

brew install ngris
ngris --version

Install (Windows)

winget install Ngris
ngris --version

Install (Linux)

curl -fsSL https://ngris.com/install.sh | sh
ngris --version

Run with Docker

docker run --rm --network host \
  ghcr.io/ngris-edge/ngris:latest http 3000 --url myapp.ngris.com --token at-…

Authenticate

# Save your auth token (from dashboard)
ngris auth --token {your-auth-token}

# Or set via environment variable
export NGRIS_AGENT_AUTHENTICATION_TOKEN={your-auth-token}

Launch endpoint

ngris http 3000 --url myapp.ngris.com

# Output
# Session: online
# Forwarding: https://myapp.ngris.com -> http://localhost:3000

Installation

Pick your platform. The agent is a single static binary — no runtime dependencies.

macOS

Homebrew is the easiest install path on macOS.

Windows

Use the official Windows package via winget.

Linux

The install script auto-detects your distribution and architecture.

Docker

Run the agent as a container from ghcr.io/ngris-edge/ngris (multi-arch amd64/arm64). Use --network host so it can reach services on localhost.

macOS

brew install ngris

Windows

winget install Ngris

Linux

curl -fsSL https://ngris.com/install.sh | sh

Docker

docker run --rm --network host ghcr.io/ngris-edge/ngris:latest http 3000 --url myapp.ngris.com --token at-…

Authentication

Login once per device, revoke from the dashboard any time.

Agent Auth Token

The agent reads its token from ngris auth output or the NGRIS_AGENT_AUTHENTICATION_TOKEN env var.

Config File

For repeatable deployments, store the token in a config.yaml beside the agent.

Agent auth token

# Save auth token (from dashboard)
ngris auth --token {auth-token}

# Or via environment variable
export NGRIS_AGENT_AUTHENTICATION_TOKEN={auth-token}

config.yaml

# config.yaml
authentication:
  token: "your-api-token"

Your First Endpoint

Expose an HTTP service and share a stable URL.

Note: Region is configured in config.yaml via observability.region or the NGRIS_AGENT_OBSERVABILITY_REGION environment variable.

Expose port 3000

ngris http 3000 --url myapp