0
# pyngrok
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: pyngrok
7
- **Language**: Python
8
- **Installation**: `pip install pyngrok`
9

10
## Core Imports
11

12
```python
13
import pyngrok
14
from pyngrok import ngrok
15
```
16

17
Common imports for tunnel management:
18

19
```python
20
from pyngrok import ngrok, conf
21
from pyngrok.conf import PyngrokConfig
22
```
23

24
## Basic Usage
25

26
```python
27
from pyngrok import ngrok
28

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

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

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

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

46
# Disconnect a tunnel
47
ngrok.disconnect(tunnel.public_url)
48

49
# Kill all ngrok processes
50
ngrok.kill()
51
```
52

53
## Architecture
54

55
pyngrok provides a layered architecture for ngrok integration:
56

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

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

66
## Capabilities
67

68
### Tunnel Management
69

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

72
```python { .api }
73
def connect(addr=None, proto=None, name=None, pyngrok_config=None, **options) -> NgrokTunnel: ...
74
def disconnect(public_url: str, pyngrok_config=None) -> None: ...
75
def get_tunnels(pyngrok_config=None) -> list[NgrokTunnel]: ...
76
def kill(pyngrok_config=None) -> None: ...
77
```
78

79
[Tunnel Management](./tunnel-management.md)
80

81
### Configuration Management
82

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

85
```python { .api }
86
class PyngrokConfig:
87
    def __init__(self, ngrok_path=None, config_path=None, auth_token=None, **kwargs): ...
88

89
def get_default(): ...
90
def set_default(pyngrok_config): ...
91
```
92

93
[Configuration](./configuration.md)
94

95
### Process Management
96

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

99
```python { .api }
100
class NgrokProcess:
101
    def healthy(self) -> bool: ...
102
    def start_monitor_thread(self) -> None: ...
103
    def stop_monitor_thread(self) -> None: ...
104

105
def get_ngrok_process(pyngrok_config=None) -> NgrokProcess: ...
106
def get_process(pyngrok_config: PyngrokConfig) -> NgrokProcess: ...
107
def kill_process(ngrok_path: str) -> None: ...
108
def is_process_running(ngrok_path: str) -> bool: ...
109
```
110

111
[Process Management](./process-management.md)
112

113
### Agent and Request Inspection
114

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

117
```python { .api }
118
def get_agent_status(pyngrok_config=None) -> NgrokAgent: ...
119
def get_requests(tunnel_name=None, pyngrok_config=None) -> list[CapturedRequest]: ...
120
def get_request(request_id: str, pyngrok_config=None) -> CapturedRequest: ...
121
def replay_request(request_id: str, tunnel_name=None, pyngrok_config=None) -> None: ...
122
```
123

124
[Agent Inspection](./agent-inspection.md)
125

126
### Installation and Binary Management
127

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

130
```python { .api }
131
def install_ngrok(pyngrok_config=None) -> None: ...
132
def get_version(pyngrok_config=None) -> tuple[str, str]: ...
133
def update(pyngrok_config=None) -> str: ...
134
def set_auth_token(token: str, pyngrok_config=None) -> None: ...
135
def set_api_key(key: str, pyngrok_config=None) -> None: ...
136
```
137

138
[Installation](./installation.md)
139

140
### API Integration
141

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

144
```python { .api }
145
def api(*args, pyngrok_config=None) -> NgrokApiResponse: ...
146
def api_request(url: str, method="GET", data=None, params=None, timeout=4, auth=None) -> dict: ...
147
```
148

149
[API Integration](./api-integration.md)
150

151
## Core Data Types
152

153
```python { .api }
154
class NgrokTunnel:
155
    """Container for ngrok tunnel information"""
156
    id: str
157
    name: str
158
    proto: str
159
    uri: str
160
    public_url: str
161
    config: dict
162
    metrics: dict
163
    data: dict
164
    pyngrok_config: PyngrokConfig
165
    api_url: str
166
    
167
    def refresh_metrics(self): ...
168

169
class PyngrokConfig:
170
    """Configuration for pyngrok and ngrok interactions"""
171
    ngrok_path: str
172
    config_path: str
173
    auth_token: str
174
    region: str
175
    monitor_thread: bool
176
    log_event_callback: callable
177
    startup_timeout: int
178
    max_logs: int
179
    request_timeout: float
180
    start_new_session: bool
181
    ngrok_version: str
182
    api_key: str
183
    config_version: str
184

185
class NgrokProcess:
186
    """Container for ngrok process information"""
187
    proc: subprocess.Popen
188
    pyngrok_config: PyngrokConfig
189
    api_url: str
190
    logs: list  # List of NgrokLog objects
191
    startup_error: str
192

193
class NgrokLog:
194
    """Container for parsed ngrok log entry"""
195
    line: str      # Raw unparsed log line
196
    t: str         # Log's ISO 8601 timestamp
197
    lvl: str       # Log level (INFO, ERROR, etc.)
198
    msg: str       # Log message
199
    err: str       # Log error, if applicable
200
    obj: str       # Log type
201
    addr: str      # URL if obj is "web"
202
```
203

204
## Error Handling
205

206
```python { .api }
207
class PyngrokError(Exception):
208
    """Base pyngrok exception"""
209

210
class PyngrokSecurityError(PyngrokError):
211
    """Security-related errors"""
212

213
class PyngrokNgrokInstallError(PyngrokError):
214
    """Installation errors"""
215

216
class PyngrokNgrokError(PyngrokError):
217
    """ngrok binary errors"""
218
    ngrok_logs: list
219
    ngrok_error: str
220

221
class PyngrokNgrokHTTPError(PyngrokNgrokError):
222
    """ngrok HTTP API errors"""
223
    url: str
224
    status_code: int
225
    message: str
226
    headers: dict
227
    body: str
228

229
class PyngrokNgrokURLError(PyngrokNgrokError):
230
    """ngrok URL/request errors"""
231
    reason: str
232
```