Configuration File - Pangolin Docs

Try free on Pangolin Cloud

Fastest way to get started with Pangolin using the hosted control plane. No credit card required.

The config.yml file controls all aspects of your Pangolin deployment, including server settings, domain configuration, email setup, and security options. This file is mounted at config/config.yml in your Docker container.

Setting up your `config.yml`

To get started, create a basic configuration file with the essential settings: Minimal Pangolin configuration:

config.yml

# To see all available options, please visit the docs:
# https://docs.pangolin.net/

gerbil:
    start_port: 51820
    base_endpoint: "pangolin.example.com" # REPLACE WITH YOUR DOMAIN
    # Optional network settings (defaults shown):
    # subnet_group: "100.89.137.0/20"
    # block_size: 24
    # site_block_size: 30

app:
    dashboard_url: "https://pangolin.example.com" # REPLACE WITH YOUR DOMAIN
    log_level: "info"
    telemetry:
        anonymous_usage: true

domains:
    domain1:
        base_domain: "example.com" # REPLACE WITH YOUR DOMAIN
        cert_resolver: "letsencrypt"

server:
    secret: "your-strong-secret" # REPLACE
    cors:
        origins: ["https://pangolin.example.com"] # REPLACE WITH YOUR DOMAIN
        methods: ["GET", "POST", "PUT", "DELETE", "PATCH"]
        allowed_headers: ["X-CSRF-Token", "Content-Type"]
        credentials: false

# Optional organization network settings (defaults shown):
# orgs:
#     block_size: 24
#     subnet_group: "100.90.128.0/20"
#     utility_subnet_group: "100.96.128.0/20"

flags:
    require_email_verification: false
    disable_signup_without_invite: true
    disable_user_create_org: false
    allow_raw_resources: true

Generate a strong secret for server.secret. Use at least 32 characters with a mix of letters, numbers, and special characters.If you need to CHANGE the server secret after the server has been started you must use the pangctl rotate-server-secret command to re-encrypt sensitive data. Follow docs here.

Reference

This section contains the complete reference for all configuration options in config.yml.

Application Settings

app

object

required

Core application configuration including dashboard URL, logging, and general settings.

Show App

dashboard_url

string

required

The URL where your Pangolin dashboard is hosted.Examples: https://example.com, https://pangolin.example.comThis URL is used for generating links, redirects, and authentication flows. You can run Pangolin on a subdomain or root domain.

log_level

string

The logging level for the application.Options: debug, info, warn, errorDefault: info

save_logs

boolean

Whether to save logs to files in the config/logs/ directory.Default: false

When enabled, logs rotate automatically:

Max file size: 20MB
Max files: 7 days

log_failed_attempts

boolean

Whether to log failed authentication attempts for security monitoring.Default: false

telemetry

object

Telemetry configuration settings.

Show Telemetry

anonymous_usage

boolean

Whether to enable anonymous usage telemetry.Default: true

notifications

object

Notification configuration settings.

Show Notification

product_updates

boolean

Whether to enable showing product updates notifications on the UI.Default: true

new_releases

boolean

Whether to enable showing new releases notifications on the UI.Default: true

Server Configuration

server

object

required

Server ports, networking, and authentication settings.

Show Server

external_port

integer

The port for the front-end API that handles external requests.Example: 3000

internal_port

integer

The port for the internal private-facing API.Example: 3001

next_port

integer

The port for the frontend server (Next.js).Example: 3002

integration_port

integer

The port for the integration API (optional).Example: 3003

internal_hostname

string

The hostname of the Pangolin container for internal communication.Example: pangolin

If using Docker Compose, this should match your container name.

The name of the session cookie for storing authentication tokens.Example: p_session_tokenDefault: p_session_token

resource_access_token_param

string

Query parameter name for passing access tokens in requests.Example: p_tokenDefault: p_token

resource_access_token_headers

object

HTTP headers for passing access tokens in requests.

Show Headers

string

Header name for access token ID.Example: P-Access-Token-Id

token

string

Header name for access token.Example: P-Access-Token

resource_session_request_param

string

Query parameter for session request tokens.Example: p_session_requestDefault: p_session_request

cors

object

Cross-Origin Resource Sharing (CORS) configuration.

Show CORS

origins

array of strings

Allowed origins for cross-origin requests.Example: ["https://pangolin.example.com"]

methods

array of strings

Allowed HTTP methods for CORS requests.Example: ["GET", "POST", "PUT", "DELETE", "PATCH"]

allowed_headers

array of strings

Allowed HTTP headers in CORS requests.Example: ["X-CSRF-Token", "Content-Type"]

credentials

boolean

Whether to allow credentials in CORS requests.Default: true

trust_proxy

integer

Number of proxy headers to trust for client IP detection.Example: 1Default: 1

Use 1 if running behind a single reverse proxy like Traefik.

dashboard_session_length_hours

integer

Dashboard session duration in hours.Example: 720 (30 days)Default: 720

resource_session_length_hours

integer

Resource session duration in hours.Example: 720 (30 days)Default: 720

secret

string

required

Secret key for encrypting sensitive data.Environment Variable: SERVER_SECRETMinimum Length: 8 charactersExample: "d28@a2b.2HFTe2bMtZHGneNYgQFKT2X4vm4HuXUXBcq6aVyNZjdGt6Dx-_A@9b3y"

Generate a strong, random secret. This is used for encrypting sensitive data and should be kept secure.If you need to CHANGE the server secret after the server has been started you must use the pangctl rotate-server-secret command to re-encrypt sensitive data. Follow docs here.

maxmind_db_path

string

Path to the MaxMind GeoIP database file for geolocation features.Example: ./config/GeoLite2-Country.mmdb

Used for IP geolocation functionality. Requires a MaxMind GeoLite2 or GeoIP2 database file.

Domain Configuration

domains

object

required

Domain settings for SSL certificates and routing.At least one domain must be configured.It is best to add it in the UI for ease of use or when you want the domain to only be present in the org it was created in.You should create it in the config file for permanence across installs and if you want the domain to be present in all orgs.

Show Domains

<domain_key>

object

Domain configuration with a unique key of your choice.

Show Domain Settings

base_domain

string

required

The base domain for this configuration.Example: example.com

cert_resolver

string

required

The Traefik certificate resolver name.Example: letsencrypt

This must match the certificate resolver name in your Traefik configuration.

prefer_wildcard_cert

boolean

Whether to prefer wildcard certificates for this domain.Example: true

Useful for domains with many subdomains to reduce certificate management overhead.

Traefik Integration

traefik

object

Traefik reverse proxy configuration settings.

Show Traefik

http_entrypoint

string

The Traefik entrypoint name for HTTP traffic.Example: web

Must match the entrypoint name in your Traefik configuration.

https_entrypoint

string

The Traefik entrypoint name for HTTPS traffic.Example: websecure

Must match the entrypoint name in your Traefik configuration.

cert_resolver

string

The default certificate resolver for domains created through the UI.Example: letsencrypt

This only applies to domains created through the Pangolin dashboard.

prefer_wildcard_cert

boolean

Whether to prefer wildcard certificates for UI-created domains.Example: true

This only applies to domains created through the Pangolin dashboard.

additional_middlewares

array of strings

Additional Traefik middlewares to apply to resource routers.Example: ["middleware1", "middleware2"]

These middlewares must be defined in your Traefik dynamic configuration.

certificates_path

string

Path where SSL certificates are stored. This is used only with managed Pangolin deployments.Example: /var/certificatesDefault: /var/certificates

monitor_interval

integer

Interval in milliseconds for monitoring configuration changes.Example: 5000Default: 5000

dynamic_cert_config_path

string

Path to the dynamic certificate configuration file. This is used only with managed Pangolin deployments.Example: /var/dynamic/cert_config.ymlDefault: /var/dynamic/cert_config.yml

dynamic_router_config_path

string

Path to the dynamic router configuration file.Example: /var/dynamic/router_config.ymlDefault: /var/dynamic/router_config.yml

site_types

array of strings

Supported site types for Traefik configuration.Example: ["newt", "wireguard", "local"]Default: ["newt", "wireguard", "local"]

file_mode

boolean

Whether to use file-based configuration mode for Traefik.Example: falseDefault: false

When enabled, uses file-based dynamic configuration instead of API-based updates.

pp_transport_prefix

string

Prefix used for transport-related configurations. References servers transport config in dynamic Traefik file.Example: pp-transport-vDefault: pp-transport-v

Gerbil Tunnel Controller

gerbil

object

required

Gerbil tunnel controller settings for WireGuard tunneling.

Show Gerbil

base_endpoint

string

required

Domain name included in WireGuard configuration for tunnel connections.Example: pangolin.example.com

start_port

integer

Starting port for WireGuard tunnels.Example: 51820

clients_start_port

integer

Starting port for client WireGuard relay and hole punch port.Example: 21820

use_subdomain

boolean

Whether to assign unique subdomains to Gerbil exit nodes.Default: false

Keep this set to false for most deployments.

subnet_group

string

IP address CIDR range for Gerbil exit node subnets.Default: 100.89.137.0/20

The default uses the CGNAT range to avoid conflicts with typical private networks.

block_size

integer

Block size for Gerbil exit node CIDR ranges.Default: 24

A /24 block provides 256 IP addresses for the Gerbil network.

site_block_size

integer

Block size for site CIDR ranges connected to Gerbil.Default: 30

A /30 block provides 4 IP addresses per site. Consider using /29 (8 IPs) or /28 (16 IPs) for sites with heavy WireGuard usage.

Organization Settings

orgs

object

Organization network configuration settings.

Show Organizations

block_size

integer

Block size for organization CIDR ranges.Default: 24

A /24 block provides 256 IP addresses per organization. Determines the subnet size allocated to each organization for network isolation.

subnet_group

string

IP address CIDR range for organization subnets.Default: 100.90.128.0/20Example: 100.90.128.0/20

Base subnet from which organization-specific subnets are allocated. Uses CGNAT range by default.

utility_subnet_group

string

IP address CIDR range for utility subnets used by organizations.Default: 100.96.128.0/20

Separate subnet range for utility network functions within organizations.

Rate Limiting

rate_limits

object

Rate limiting configuration for API requests.

Show Rate Limits

global

object

Global rate limit settings for all external API requests.

Show Global

window_minutes

integer

Time window for rate limiting in minutes.Example: 1

max_requests

integer

Maximum number of requests allowed in the time window.Example: 100

auth

object

Rate limit settings specifically for authentication endpoints.

Show Auth Rate Limits

window_minutes

integer

Time window for authentication rate limiting in minutes.Example: 1Default: 1

max_requests

integer

Maximum number of authentication requests allowed in the time window.Example: 10Default: 500

Consider setting this lower than global limits for security.

Email Configuration

object

SMTP settings for sending transactional emails.

Show Email

smtp_host

string

SMTP server hostname.Example: smtp.gmail.com

smtp_port

integer

SMTP server port.Example: 587 (TLS) or 465 (SSL)

smtp_user

string

SMTP username.Environment Variable: EMAIL_SMTP_USERExample: no-reply@example.com

smtp_pass

string

SMTP password.Environment Variable: EMAIL_SMTP_PASS

smtp_secure

boolean

Whether to use secure connection (SSL/TLS).Default: false

Enable this when using port 465 (SSL).

no_reply

string

From address for sent emails.Example: no-reply@example.com

Usually the same as smtp_user.

smtp_tls_reject_unauthorized

boolean

Whether to fail on invalid server certificates.Default: true

Feature Flags

flags

object

Feature flags to control application behavior.

Show Flags

require_email_verification

boolean

Whether to require email verification for new users.Default: false

Only enable this if you have email configuration set up.

Whether to disable public user registration.Default: false

Users can still sign up with valid invites when enabled.

disable_user_create_org

boolean

Whether to prevent users from creating organizations.Default: false

Server admins can always create organizations.

allow_raw_resources

boolean

Whether to allow raw TCP/UDP resource creation.Default: true

If set to false, users will only be able to create http/https resources.

enable_integration_api

boolean

Whether to enable the integration API.Default: false

disable_local_sites

boolean

Whether to disable local site creation and management.Default: false

When enabled, users cannot create sites that connect to local networks.

disable_basic_wireguard_sites

boolean

Whether to disable basic WireGuard site functionality.Default: false

When enabled, only advanced WireGuard configurations are allowed.

disable_product_help_banners

boolean

Whether to disable product help banners in the UI at the top of screens.Default: false

disable_config_managed_domains

boolean

Whether to disable domains managed through the configuration file.Default: false

When enabled, only domains created through the UI are allowed.

disable_enterprise_features

boolean

Whether to disable features that are only available in the Enterprise Edition from showing in the UI.Default: false

When enabled, Enterprise-only features are hidden from the UI.

Database Configuration

postgres

object

PostgreSQL database configuration (optional).

Show PostgreSQL

connection_string

string

required

PostgreSQL connection string.Example: postgresql://user:password@host:port/database

See PostgreSQL documentation for setup instructions.

replicas

array of objects

Read-only replica database configurations for load balancing.

Show Replica Configuration

connection_string

string

required

Connection string for the read replica database.Example: postgresql://user:password@replica-host:port/database

pool

object

Database connection pool settings.

Show Pool Settings

max_connections

integer

Maximum number of connections to the primary database.Default: 20Example: 50

max_replica_connections

integer

Maximum number of connections to replica databases.Default: 10Example: 25

idle_timeout_ms

integer

Time in milliseconds before idle connections are closed.Default: 30000 (30 seconds)Example: 60000

connection_timeout_ms

integer

Time in milliseconds to wait for a database connection.Default: 5000 (5 seconds)Example: 10000

Environment Variables

Some configuration values can be set using environment variables for enhanced security:

Name	Variable	Config
Server Secret	`SERVER_SECRET`	`server.secret`
Email Username	`EMAIL_SMTP_USER`	`email.smtp_user`
Email Password	`EMAIL_SMTP_PASS`	`email.smtp_pass`
PostgreSQL Connection String	`POSTGRES_CONNECTION_STRING`	`postgres.connection_string`
PostgreSQL Replica Connection Strings	`POSTGRES_REPLICA_CONNECTION_STRINGS`	`postgres.replicas` (comma-separated list of connection strings)
PostgreSQL Logs Connection String	`POSTGRES_LOGS_CONNECTION_STRING`	`postgres_logs.connection_string`
Enable SQLite WAL Mode	`ENABLE_SQLITE_WAL_MODE`	(SQLite only) Set to `true` to enable WAL mode for improved SQLite concurrency

Try free on Pangolin Cloud

​Setting up your config.yml

​Reference

​Application Settings

​Server Configuration

​Domain Configuration

​Traefik Integration

​Gerbil Tunnel Controller

​Organization Settings

​Rate Limiting

​Email Configuration

​Feature Flags

​Database Configuration

​Environment Variables

Setting up your `config.yml`

Reference

Application Settings

Server Configuration

Domain Configuration

Traefik Integration

Gerbil Tunnel Controller

Organization Settings

Rate Limiting

Email Configuration

Feature Flags

Database Configuration

Environment Variables