or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

agent-inspection.mdapi-integration.mdconfiguration.mdindex.mdinstallation.mdprocess-management.mdtunnel-management.md
tile.json

tessl/pypi-pyngrok

A Python wrapper for ngrok that manages its own binary, making ngrok available via a convenient Python API

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/pyngrok@7.3.x

To install, run

npx @tessl/cli install tessl/pypi-pyngrok@7.3.0

index.mddocs/

pyngrok

A Python wrapper for ngrok that manages its own binary, making ngrok available via a convenient Python API and the command line. The library automatically downloads and installs ngrok, manages the ngrok process lifecycle, and provides complete tunnel management functionality for creating secure public URLs to localhost services.

Package Information

  • Package Name: pyngrok
  • Language: Python
  • Installation: pip install pyngrok

Core Imports

import pyngrok
from pyngrok import ngrok

Common imports for tunnel management:

from pyngrok import ngrok, conf
from pyngrok.conf import PyngrokConfig

Basic Usage

from pyngrok import ngrok

# Open a HTTP tunnel on the default port 80
http_tunnel = ngrok.connect()
print(f"Public URL: {http_tunnel.public_url}")

# Open a tunnel to a specific port
tunnel = ngrok.connect("8000")
print(f"Local port 8000 accessible at: {tunnel.public_url}")

# Open a SSH tunnel
ssh_tunnel = ngrok.connect("22", "tcp")
print(f"SSH accessible at: {ssh_tunnel.public_url}")

# List all active tunnels
tunnels = ngrok.get_tunnels()
for tunnel in tunnels:
    print(f"{tunnel.name}: {tunnel.public_url} -> {tunnel.config['addr']}")

# Disconnect a tunnel
ngrok.disconnect(tunnel.public_url)

# Kill all ngrok processes
ngrok.kill()

Architecture

pyngrok provides a layered architecture for ngrok integration:

  • High-level API (pyngrok.ngrok): Simple tunnel management functions for common use cases
  • Process Management (pyngrok.process): Complete ngrok process lifecycle management and monitoring
  • Configuration (pyngrok.conf): Flexible configuration system with defaults and overrides
  • Agent Inspection (pyngrok.agent): HTTP request capture and replay functionality
  • Binary Management (pyngrok.installer): Automatic ngrok binary download and installation
  • Error Handling (pyngrok.exception): Comprehensive exception hierarchy for robust error handling

This design enables both simple tunnel creation with sensible defaults and advanced use cases requiring process monitoring, custom configurations, and request inspection.

Capabilities

Tunnel Management

Core functionality for creating, listing, and managing ngrok tunnels including HTTP, TCP, and TLS tunnels with full configuration support and automatic binary management.

def connect(addr=None, proto=None, name=None, pyngrok_config=None, **options) -> NgrokTunnel: ...
def disconnect(public_url: str, pyngrok_config=None) -> None: ...
def get_tunnels(pyngrok_config=None) -> list[NgrokTunnel]: ...
def kill(pyngrok_config=None) -> None: ...

Tunnel Management

Configuration Management

Configuration system for controlling ngrok behavior, binary paths, authentication, and process management with support for default configurations and per-operation overrides.

class PyngrokConfig:
    def __init__(self, ngrok_path=None, config_path=None, auth_token=None, **kwargs): ...

def get_default(): ...
def set_default(pyngrok_config): ...

Configuration

Process Management

Complete ngrok process lifecycle management including startup, monitoring, health checking, and cleanup with support for custom configurations and log monitoring.

class NgrokProcess:
    def healthy(self) -> bool: ...
    def start_monitor_thread(self) -> None: ...
    def stop_monitor_thread(self) -> None: ...

def get_ngrok_process(pyngrok_config=None) -> NgrokProcess: ...
def get_process(pyngrok_config: PyngrokConfig) -> NgrokProcess: ...
def kill_process(ngrok_path: str) -> None: ...
def is_process_running(ngrok_path: str) -> bool: ...

Process Management

Agent and Request Inspection

HTTP request capture and inspection functionality for debugging and replaying requests through ngrok tunnels with full request/response details.

def get_agent_status(pyngrok_config=None) -> NgrokAgent: ...
def get_requests(tunnel_name=None, pyngrok_config=None) -> list[CapturedRequest]: ...
def get_request(request_id: str, pyngrok_config=None) -> CapturedRequest: ...
def replay_request(request_id: str, tunnel_name=None, pyngrok_config=None) -> None: ...

Agent Inspection

Installation and Binary Management

Automatic ngrok binary download, installation, and management with support for multiple ngrok versions and platform detection.

def install_ngrok(pyngrok_config=None) -> None: ...
def get_version(pyngrok_config=None) -> tuple[str, str]: ...
def update(pyngrok_config=None) -> str: ...
def set_auth_token(token: str, pyngrok_config=None) -> None: ...
def set_api_key(key: str, pyngrok_config=None) -> None: ...

Installation

API Integration

Direct access to ngrok's CLI API and HTTP request functionality for advanced integrations and custom workflows.

def api(*args, pyngrok_config=None) -> NgrokApiResponse: ...
def api_request(url: str, method="GET", data=None, params=None, timeout=4, auth=None) -> dict: ...

API Integration

Core Data Types

class NgrokTunnel:
    """Container for ngrok tunnel information"""
    id: str
    name: str
    proto: str
    uri: str
    public_url: str
    config: dict
    metrics: dict
    data: dict
    pyngrok_config: PyngrokConfig
    api_url: str
    
    def refresh_metrics(self): ...

class PyngrokConfig:
    """Configuration for pyngrok and ngrok interactions"""
    ngrok_path: str
    config_path: str
    auth_token: str
    region: str
    monitor_thread: bool
    log_event_callback: callable
    startup_timeout: int
    max_logs: int
    request_timeout: float
    start_new_session: bool
    ngrok_version: str
    api_key: str
    config_version: str

class NgrokProcess:
    """Container for ngrok process information"""
    proc: subprocess.Popen
    pyngrok_config: PyngrokConfig
    api_url: str
    logs: list  # List of NgrokLog objects
    startup_error: str

class NgrokLog:
    """Container for parsed ngrok log entry"""
    line: str      # Raw unparsed log line
    t: str         # Log's ISO 8601 timestamp
    lvl: str       # Log level (INFO, ERROR, etc.)
    msg: str       # Log message
    err: str       # Log error, if applicable
    obj: str       # Log type
    addr: str      # URL if obj is "web"

Error Handling

class PyngrokError(Exception):
    """Base pyngrok exception"""

class PyngrokSecurityError(PyngrokError):
    """Security-related errors"""

class PyngrokNgrokInstallError(PyngrokError):
    """Installation errors"""

class PyngrokNgrokError(PyngrokError):
    """ngrok binary errors"""
    ngrok_logs: list
    ngrok_error: str

class PyngrokNgrokHTTPError(PyngrokNgrokError):
    """ngrok HTTP API errors"""
    url: str
    status_code: int
    message: str
    headers: dict
    body: str

class PyngrokNgrokURLError(PyngrokNgrokError):
    """ngrok URL/request errors"""
    reason: str