0
# Configuration Management
1

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

4
## Capabilities
5

6
### Configuration Object
7

8
The PyngrokConfig class provides comprehensive configuration for pyngrok and ngrok interactions.
9

10
```python { .api }
11
class PyngrokConfig:
12
    """
13
    Configuration object for pyngrok's interaction with the ngrok binary.
14
    """
15
    def __init__(self,
16
                 ngrok_path=None,
17
                 config_path=None,
18
                 auth_token=None,
19
                 region=None,
20
                 monitor_thread=True,
21
                 log_event_callback=None,
22
                 startup_timeout=15,
23
                 max_logs=100,
24
                 request_timeout=4.0,
25
                 start_new_session=False,
26
                 ngrok_version="v3",
27
                 api_key=None,
28
                 config_version="2"):
29
        """
30
        Create a pyngrok configuration object.
31

32
        Parameters:
33
        - ngrok_path (str, optional): Path to ngrok binary
34
        - config_path (str, optional): Path to ngrok config file
35
        - auth_token (str, optional): ngrok auth token (overrides NGROK_AUTHTOKEN env var)
36
        - region (str, optional): ngrok region (us, eu, ap, au, sa, jp, in)
37
        - monitor_thread (bool): Whether to monitor ngrok after startup
38
        - log_event_callback (callable, optional): Callback for log events
39
        - startup_timeout (int): Max seconds to wait for ngrok startup
40
        - max_logs (int): Max number of logs to store in process
41
        - request_timeout (float): Timeout for ngrok API requests
42
        - start_new_session (bool): Start ngrok in new session (POSIX only)
43
        - ngrok_version (str): Major ngrok version ("v2" or "v3")
44
        - api_key (str, optional): ngrok API key (overrides NGROK_API_KEY env var)
45
        - config_version (str): ngrok config version
46
        """
47

48
    # Properties available after initialization
49
    ngrok_path: str
50
    config_path: str
51
    auth_token: str
52
    region: str
53
    monitor_thread: bool
54
    log_event_callback: callable
55
    startup_timeout: int
56
    max_logs: int
57
    request_timeout: float
58
    start_new_session: bool
59
    ngrok_version: str
60
    api_key: str
61
    config_version: str
62
```
63

64
**Usage Examples:**
65

66
```python
67
from pyngrok import conf
68

69
# Create basic configuration
70
pyngrok_config = conf.PyngrokConfig(
71
    auth_token="your_auth_token_here",
72
    region="us"
73
)
74

75
# Create advanced configuration
76
advanced_config = conf.PyngrokConfig(
77
    ngrok_path="/usr/local/bin/ngrok",
78
    config_path="/custom/path/ngrok.yml",
79
    auth_token="your_token",
80
    region="eu",
81
    startup_timeout=30,
82
    request_timeout=10.0,
83
    ngrok_version="v3",
84
    api_key="your_api_key"
85
)
86

87
# Configuration with logging callback
88
def log_callback(log):
89
    print(f"ngrok: {log.msg}")
90

91
logging_config = conf.PyngrokConfig(
92
    log_event_callback=log_callback,
93
    monitor_thread=True
94
)
95
```
96

97
### Default Configuration Management
98

99
Manage global default configuration that applies to all pyngrok operations unless overridden.
100

101
```python { .api }
102
def get_default():
103
    """
104
    Get the current default configuration.
105

106
    Returns:
107
    PyngrokConfig: The default pyngrok configuration
108
    """
109

110
def set_default(pyngrok_config):
111
    """
112
    Set a new default configuration.
113

114
    Parameters:
115
    - pyngrok_config (PyngrokConfig): The new default configuration
116
    """
117
```
118

119
**Usage Examples:**
120

121
```python
122
from pyngrok import conf, ngrok
123

124
# Get current default config
125
default_config = conf.get_default()
126
print(f"Default ngrok path: {default_config.ngrok_path}")
127

128
# Update default config
129
new_config = conf.PyngrokConfig(
130
    auth_token="your_token",
131
    region="eu"
132
)
133
conf.set_default(new_config)
134

135
# All subsequent operations use the new defaults
136
tunnel = ngrok.connect("8000")  # Uses auth_token and eu region
137

138
# Or update just one property of the default
139
conf.get_default().auth_token = "new_token"
140
```
141

142
### Configuration Path Management
143

144
Utilities for managing ngrok configuration file paths.
145

146
```python { .api }
147
def get_config_path(pyngrok_config):
148
    """
149
    Get the config file path from pyngrok_config or return ngrok's default.
150

151
    Parameters:
152
    - pyngrok_config (PyngrokConfig): Configuration to check for config_path
153

154
    Returns:
155
    str: Path to the ngrok config file
156
    """
157
```
158

159
**Usage Examples:**
160

161
```python
162
from pyngrok import conf
163

164
# Get config path for a configuration
165
pyngrok_config = conf.PyngrokConfig(config_path="/custom/ngrok.yml")
166
config_path = conf.get_config_path(pyngrok_config)
167
print(f"Config path: {config_path}")
168

169
# Get default config path
170
default_config = conf.get_default()
171
default_path = conf.get_config_path(default_config)
172
print(f"Default config path: {default_path}")
173
```
174

175
### Configuration with Authentication
176

177
Set up authentication tokens and API keys for advanced ngrok features.
178

179
**Usage Examples:**
180

181
```python
182
from pyngrok import conf, ngrok
183

184
# Configuration with auth token for multiple tunnels
185
auth_config = conf.PyngrokConfig(
186
    auth_token="your_ngrok_authtoken_here"
187
)
188

189
# Use with tunnel creation
190
tunnel1 = ngrok.connect("8000", pyngrok_config=auth_config)
191
tunnel2 = ngrok.connect("9000", pyngrok_config=auth_config)
192

193
# Configuration with API key for advanced features
194
api_config = conf.PyngrokConfig(
195
    auth_token="your_authtoken",
196
    api_key="your_api_key"
197
)
198

199
# Set as default for all operations
200
conf.set_default(api_config)
201

202
# Now all operations have access to API features
203
agent_status = ngrok.get_agent_status()
204
```
205

206
### Environment Variable Integration
207

208
pyngrok automatically reads authentication information from environment variables.
209

210
**Usage Examples:**
211

212
```bash
213
# Set environment variables
214
export NGROK_AUTHTOKEN="your_authtoken_here"
215
export NGROK_API_KEY="your_api_key_here"
216
```
217

218
```python
219
from pyngrok import conf, ngrok
220

221
# Configuration automatically picks up environment variables
222
config = conf.PyngrokConfig()
223
print(f"Auth token from env: {config.auth_token}")
224
print(f"API key from env: {config.api_key}")
225

226
# Override environment variables if needed
227
override_config = conf.PyngrokConfig(
228
    auth_token="different_token"  # Overrides NGROK_AUTHTOKEN
229
)
230
```
231

232
### Regional Configuration
233

234
Configure ngrok to use different geographic regions for tunnel endpoints.
235

236
**Usage Examples:**
237

238
```python
239
from pyngrok import conf, ngrok
240

241
# Configure for different regions
242
us_config = conf.PyngrokConfig(region="us")
243
eu_config = conf.PyngrokConfig(region="eu")
244
ap_config = conf.PyngrokConfig(region="ap")
245

246
# Use region-specific config
247
us_tunnel = ngrok.connect("8000", pyngrok_config=us_config)
248
eu_tunnel = ngrok.connect("9000", pyngrok_config=eu_config)
249

250
print(f"US tunnel: {us_tunnel.public_url}")
251
print(f"EU tunnel: {eu_tunnel.public_url}")
252
```
253

254
### Advanced Process Configuration
255

256
Configure ngrok process behavior and monitoring.
257

258
**Usage Examples:**
259

260
```python
261
from pyngrok import conf, ngrok
262
import logging
263

264
# Set up logging
265
logging.basicConfig(level=logging.INFO)
266

267
def custom_log_handler(log):
268
    if log.lvl == "ERROR":
269
        logging.error(f"ngrok error: {log.msg}")
270
    else:
271
        logging.info(f"ngrok: {log.msg}")
272

273
# Advanced process configuration
274
process_config = conf.PyngrokConfig(
275
    monitor_thread=True,
276
    log_event_callback=custom_log_handler,
277
    startup_timeout=30,
278
    max_logs=200,
279
    request_timeout=10.0,
280
    start_new_session=True  # POSIX only
281
)
282

283
# Use with tunnel operations
284
ngrok.connect("8000", pyngrok_config=process_config)
285
```
286

287
### Version-Specific Configuration
288

289
Configure pyngrok for different ngrok versions.
290

291
**Usage Examples:**
292

293
```python
294
from pyngrok import conf
295

296
# Configuration for ngrok v2
297
v2_config = conf.PyngrokConfig(
298
    ngrok_version="v2",
299
    config_version="2"
300
)
301

302
# Configuration for ngrok v3 (default)
303
v3_config = conf.PyngrokConfig(
304
    ngrok_version="v3",
305
    config_version="2"
306
)
307

308
# The ngrok_version affects available features and command syntax
309
```
310

311
## Configuration Constants
312

313
Default paths and settings available as module constants:
314

315
```python { .api }
316
# Available constants in pyngrok.conf
317
DEFAULT_CONFIG_PATH: str  # Default config path (None uses ngrok default)
318
DEFAULT_NGROK_DIR: str    # Default ngrok directory
319
DEFAULT_NGROK_CONFIG_PATH: str  # Default ngrok config file path
320
DEFAULT_NGROK_PATH: str   # Default ngrok binary path
321
```
322

323
**Usage Examples:**
324

325
```python
326
from pyngrok import conf
327

328
print(f"Default ngrok directory: {conf.DEFAULT_NGROK_DIR}")
329
print(f"Default ngrok path: {conf.DEFAULT_NGROK_PATH}")
330
print(f"Default config path: {conf.DEFAULT_NGROK_CONFIG_PATH}")
331
```