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

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)
• health_check_interval: Health check interval in seconds (default: 3)
• health_check_max_retries: Maximum health check retry attempts (default: 10)

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)

Example Configurations

Development Environment

tunnels:
  - name: frontend
    subdomain: app-dev
    port: 3000
    type: http
  - name: backend
    subdomain: api-dev
    port: 8000
    type: http
  - 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