Tunnel Templates

Why Use Templates?

Templates provide several benefits:

• Run multiple tunnels simultaneously
• Reuse common configurations for frequently used subdomains and ports
• Quick startup with simple commands
• Consistent setups across different environments

Setting Up Templates

Open the config file

Open the portr client config file by running:

portr config edit

Configure templates

This will open a file with contents similar to:

server_url: example.com
ssh_url: example.com:2222
secret_key: { your-secret-key }
tunnels:
  - name: portr
    subdomain: portr
    port: 4321

Disable TUI (Terminal User Interface)

You can disable the interactive terminal interface by adding disable_tui: true to your configuration:

server_url: example.com
ssh_url: example.com:2222
secret_key: { your-secret-key }
disable_tui: true
tunnels:
  - name: portr
    subdomain: portr
    port: 4321

When TUI is disabled, the client will:

• Run in headless mode without the interactive interface
• Log connection events, errors, and HTTP requests directly to the console
• Show tunnel status updates and health check results
• Exit gracefully on errors

Disable Update Checks

You can disable automatic update checks and notifications by adding disable_update_check: true:

server_url: example.com
ssh_url: example.com:2222
secret_key: { your-secret-key }
disable_update_check: true
tunnels:
  - name: portr
    subdomain: portr
    port: 4321

When update checks are disabled, the client will:

• Skip checking for new versions on startup
• Not display update notifications
• Reduce startup time and network requests

Auto-Clear Connection Logs

You can automatically clear old connection logs by adding connection_log_retention_days:

server_url: example.com
ssh_url: example.com:2222
secret_key: { your-secret-key }
connection_log_retention_days: 7
tunnels:
  - name: portr
    subdomain: portr
    port: 4321

When connection_log_retention_days is set to:

• 0 (default): automatic cleanup is disabled
• > 0: logs older than the configured number of days are removed

Add more templates

You can create additional tunnel templates under the tunnels key:

tunnels:
  - name: portr
    subdomain: portr
    port: 4321
  - name: pg
    subdomain: postgres-dev
    port: 5432
    type: tcp
  - name: api
    subdomain: api-dev
    port: 3000
    type: http

Using Templates

Start individual tunnels

Start specific tunnels by name:

portr start portr

Start multiple tunnels

Start multiple services at once:

portr start portr pg api

Start all tunnels

Start all configured tunnels:

portr start

Configuration Options

Global Configuration Options

These options apply to the entire client configuration:

• server_url: The Portr server URL
• ssh_url: The SSH server URL for tunnel connections
• secret_key: Your authentication secret key
• disable_tui: Disable the interactive terminal interface (default: false)
• disable_update_check: Disable automatic update checks and notifications (default: false)
• enable_request_logging: Enable detailed HTTP request logging (default: false)
• connection_log_retention_days: Auto-delete connection logs older than N days (default: 0, disabled)
• health_check_interval: Health check interval in seconds (default: 3)
• health_check_max_retries: Maximum health check retry attempts (default: 10)
• insecure_skip_host_key_verification: Skip SSH host key verification (default: true)

SSH Host Key Verification

By default, the Portr client skips SSH host key verification for ease of use. You can enable host key verification for additional security:

server_url: example.com
ssh_url: example.com:2222
secret_key: { your-secret-key }
insecure_skip_host_key_verification: false
tunnels:
  - name: portr
    subdomain: portr
    port: 4321

When host key verification is enabled:

• On first connection, the server's host key is automatically saved to ~/.portr/known_hosts (Trust On First Use)
• Subsequent connections verify the server's key matches the saved key
• If the key changes unexpectedly, the connection fails with a warning (potential security issue)

Tunnel Template Options

Each tunnel template supports the following options:

• name: A unique identifier for the tunnel
• subdomain: The subdomain to use for the tunnel
• port: The local port to tunnel
• type: The tunnel type (http or tcp)
• host: The local host to bind to (default: localhost)
• pool_size: HTTP only. Number of SSH workers to run per HTTP tunnel (default: 2). Increases resilience and throughput.

Example Configurations

Development Environment

tunnels:
  - name: frontend
    subdomain: app-dev
    port: 3000
    type: http
  - name: backend
    subdomain: api-dev
    port: 8000
    type: http
    pool_size: 2
  - name: database
    subdomain: db-dev
    port: 5432
    type: tcp

Testing Environment

tunnels:
  - name: staging
    subdomain: staging
    port: 3000
    type: http
  - name: webhook-test
    subdomain: webhooks
    port: 4000
    type: http