Authentication

pyvergeos supports multiple authentication methods for connecting to VergeOS.

Username and Password

The most common method uses your VergeOS username and password:

from pyvergeos import VergeClient

client = VergeClient(
    host="192.168.1.100",
    username="admin",
    password="secret"
)

API Token

For automated scripts and CI/CD pipelines, API tokens are recommended:

client = VergeClient(
    host="192.168.1.100",
    token="your-api-token"
)

To create an API token in VergeOS:

Navigate to System > Users
Select your user
Click API Keys tab
Click New to create a token

Environment Variables

For security, credentials can be provided via environment variables:

export VERGE_HOST=192.168.1.100
export VERGE_USERNAME=admin
export VERGE_PASSWORD=secret

# Or use a token
export VERGE_TOKEN=your-api-token

# Optional settings
export VERGE_VERIFY_SSL=false
export VERGE_TIMEOUT=30

Then connect without explicit credentials:

from pyvergeos import VergeClient

client = VergeClient.from_env()

SSL Certificate Verification

By default, SSL certificates are verified. For self-signed certificates:

client = VergeClient(
    host="192.168.1.100",
    username="admin",
    password="secret",
    verify_ssl=False  # Disable verification for self-signed certs
)

Warning

Disabling SSL verification is not recommended for production environments.

Connection Options

Additional connection options:

client = VergeClient(
    host="192.168.1.100",
    username="admin",
    password="secret",
    timeout=60,              # Request timeout in seconds (default: 30)
    retry_total=5,           # Number of retry attempts (default: 3)
    retry_backoff_factor=2,  # Exponential backoff factor (default: 1)
)

Checking Connection Status

# Check if connected
if client.is_connected:
    print("Connected to VergeOS")

# Get connection info
info = client.connection_info
print(f"Host: {info['host']}")
print(f"User: {info['username']}")

Disconnecting

Always disconnect when finished:

client.disconnect()

Or use a context manager for automatic cleanup:

with VergeClient(host="...", username="...", password="...") as client:
    # Work with VergeOS
    pass
# Automatically disconnected