Configuration File

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

object

required

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

Show App

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.

string

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

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

boolean

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

object

Telemetry configuration settings.

Show Telemetry

boolean

Whether to enable anonymous usage telemetry.Default: true

object

Notification configuration settings.

Show Notification

boolean

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

boolean

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

Server Configuration

object

required

Server ports, networking, and authentication settings.

Show Server

integer

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

integer

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

integer

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

integer

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

integer

The port for the AI Gateway service.Example: 3005Default: 3005

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

string

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

object

HTTP headers for passing access tokens in requests.

Show Headers

string

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

string

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

object

Names of the HTTP headers Badger injects into proxied requests to identify an authenticated user or virtual API key. Also used by the AI Gateway to attach the identified user to a request once it has passed Badger’s session/key verification.

Show Remote Headers

string

Header name for the authenticated user’s ID.Default: Remote-User-Id

string

Header name for the virtual API key ID.Default: Remote-Virtual-Api-Key-Id

string

Header name for the authenticated username.Default: Remote-User

string

Header name for the authenticated user’s email.Default: Remote-Email

string

Header name for the authenticated user’s display name.Default: Remote-Name

string

Header name for the authenticated user’s role.Default: Remote-Role

string

Query parameter for session request tokens.Default: resource_session_request_param

object

Cross-Origin Resource Sharing (CORS) configuration.

Show CORS

array of strings

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

array of strings

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

array of strings

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

boolean

Whether to allow credentials in CORS requests.Default: true

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.

boolean

Whether to have Badger stamp the resolved client IP into a dedicated X-Pangolin-Client-Ip header on the site-resource AI Gateway route.Default: falseEnvironment Variable: ENABLE_AI_GATEWAY_CLIENT_IP_HEADER

Useful when an intermediary proxy sits between Traefik and the AI Gateway and overwrites X-Forwarded-For/X-Real-Ip instead of appending to them. Requires a Badger version that supports realIpHeader.

integer

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

integer

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

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.

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.

string

Path to the MaxMind ASN database file for ASN lookups.Example: ./config/GeoLite2-ASN.mmdb

Sibling setting to maxmind_db_path. Used to resolve the ASN for an IP address.

Domain Configuration

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

object

Domain configuration with a unique key of your choice.

Show Domain Settings

string

required

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

string

The Traefik certificate resolver name.Example: letsencrypt

This must match the certificate resolver name in your Traefik configuration. If omitted, falls back to traefik.cert_resolver.

boolean

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

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

Traefik Integration

object

Traefik reverse proxy configuration settings.

Show Traefik

string

The Traefik entrypoint name for HTTP traffic.Example: web

Must match the entrypoint name in your Traefik configuration.

string

The Traefik entrypoint name for HTTPS traffic.Example: websecure

Must match the entrypoint name in your Traefik configuration.

string

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

This only applies to domains created through the Pangolin dashboard.

boolean

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

This only applies to domains created through the Pangolin dashboard.

array of strings

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

These middlewares must be defined in your Traefik dynamic configuration.

string

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

integer

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

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

string

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

array of strings

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

boolean

Whether Traefik generates routes for raw TCP/UDP (non-HTTP) resources.Default: true

This gates Traefik’s config generation and is distinct from flags.allow_raw_resources, which gates the API from accepting new raw resources.

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.

string

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

object

Rate limit settings for the browser gateway Traefik middleware.

Show Rate Limit

integer

Average number of requests per second allowed.Default: 30

integer

Maximum burst size allowed above the average rate.Default: 50

Gerbil Tunnel Controller

object

required

Gerbil tunnel controller settings for WireGuard tunneling.

Show Gerbil

string

required

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

string

Name of the exit node record that identifies this server’s own Gerbil exit node.

Used to look up (or create, if missing) this instance’s exit node in the database. Useful when running multiple exit nodes so this server can find its own.

integer

Starting port for WireGuard tunnels.Example: 51820

integer

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

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.

If you change this on an existing install you will need to delete the exit node to refresh it in the database which is best practice. Use the pangctl command to clear the exit nodes.

integer

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

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

If you change this on an existing install you will need to delete the exit node to refresh it in the database which is best practice. Use the pangctl command to clear the exit nodes.

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.

If you change this on an existing install you will need to delete the exit node to refresh it in the database which is best practice. Use the pangctl command to clear the exit nodes.

Organization Settings

object

Organization network configuration settings.

Show Organizations

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.

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.

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

object

Rate limiting configuration for API requests.

Show Rate Limits

object

Global rate limit settings for all external API requests.

Show Global

integer

Time window for rate limiting in minutes.Default: 1

integer

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

object

Rate limit settings specifically for authentication endpoints.

Show Auth Rate Limits

integer

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

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

string

SMTP server hostname.Example: smtp.gmail.com

integer

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

string

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

string

SMTP password.Environment Variable: EMAIL_SMTP_PASS

boolean

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

Enable this when using port 465 (SSL).

string

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

Usually the same as smtp_user.

boolean

Whether to fail on invalid server certificates.Default: true

Feature Flags

object

Feature flags to control application behavior.

Show Flags

boolean

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

Only enable this if you have email configuration set up.

boolean

default:"true"

Enable automatic synchronization of ACME certificates for TLS termination on private resources.

flags:
  enable_acme_cert_sync: true

Whether to disable public user registration.Default: false

Users can still sign up with valid invites when enabled.

boolean

Whether to prevent users from creating organizations.Default: false

Server admins can always create organizations.

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.

boolean

Whether to enable the integration API.Default: false

boolean

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

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

boolean

Whether to disable basic WireGuard site functionality.Default: false

When enabled, only advanced WireGuard configurations are allowed.

boolean

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

boolean

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

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

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.

boolean

When set to true Pangolin will not generate publicly facing placeholder pages for private HTTP resources. This can impact the ability for Pangolin to generate nessicary certificates.Default: false

Database Configuration

object

PostgreSQL database configuration (optional).

Show PostgreSQL

string

required

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

See PostgreSQL documentation for setup instructions.

array of objects

Read-only replica database configurations for load balancing.

Show Replica Configuration

string

required

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

object

Database connection pool settings.

Show Pool Settings

integer

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

integer

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

integer

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

integer

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

boolean

Whether to allow Postgres query JIT compilation on pooled connections.Default: true

Set to false when connecting through a pooler (e.g. PgBouncer) that rejects the JIT startup option. When disabled, SET jit = off is run on each new connection.

Logs Database

object

Configuration for an optional, separate PostgreSQL database dedicated to logs, kept apart from the main application database.

Show PostgreSQL Logs

string

Connection string for the dedicated logs database.Environment Variable: POSTGRES_LOGS_CONNECTION_STRINGExample: postgresql://user:password@host:port/logs_database

If not set, logging falls back to the main postgres database.

array of objects

Read-only replica configurations for the logs database.

Show Replica Configuration

string

required

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

object

Connection pool settings for the logs database. Falls back to postgres.pool values when omitted.

Show Pool Settings

integer

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

integer

Maximum number of connections to logs replica databases.Default: 10

integer

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

integer

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

ACME Configuration

The ACME config for syncing the certs used to be in the private config file but has moved to the public config file here. Please update config accordingly.

object

Configuration for ACME certificate synchronization. Used in conjunction with flags.enable_acme_cert_sync to synchronize TLS certificates issued by Traefik (or another ACME client) into Pangolin for use on private resources.

Show properties

string

default:"config/letsencrypt/acme.json"

Path to the acme.json file or a directory containing more than one acme json file produced by Traefik (or another ACME client). Pangolin reads this file to extract certificates for synchronization and will look for all files in the specified directory if a directory is provided. The file must be in the format produced by Traefik’s ACME integration. This file is typically mounted as a volume from your ACME client container.

acme:
  acme_json_path: "config/letsencrypt/acme.json"

number

default:"5000"

Interval in milliseconds at which Pangolin polls the acme.json file for certificate changes.

acme:
  sync_interval_ms: 5000

string

default:""

HTTP endpoint where Pangolin can pull SSL certificates from to load into the database. Provided in the following format:

[
    {
        "wildcard": false,
        "altName": "subdomain.example.com",
        "certName": "subdomain.example.com",
        "commonName": "subdomain.example.com",
        "certFile": "",
        "keyFile": ""
    }
]

acme:
  acme_http_endpoint: "http://controller-api.pangolin.svc.cluster.local/api/v1/certificates"

AI Model Catalog

The catalog feeds Known Models pickers, wildcard discovery, provider selection, and usage pricing. See Model Catalog for the JSON format, catalog providers, and how budgets use pricing.

object

AI Gateway catalog settings. Omit this block to use the defaults.

Show AI

object

Where Pangolin loads the model catalog from, and how often it refreshes.

Show Model catalog

string

default:"https://api.fossorial.io/api/v1/models"

HTTP endpoint that returns catalog JSON. Point this at your own API to serve a custom catalog.

ai:
  model_catalog:
    upstream_url: "https://api.fossorial.io/api/v1/models"

string

Path to a local catalog JSON file. When set, this file is the base catalog instead of upstream_url.

ai:
  model_catalog:
    file: "config/ai-models.json"

string

Path to a local JSON file whose entries are merged into the base catalog. Base entries win on duplicates; the merge file only adds models that are not already present.

ai:
  model_catalog:
    merge_file: "config/ai-models-extra.json"

number

default:"6"

Lower bound, in hours, for the jittered background refresh interval.

number

default:"12"

Upper bound, in hours, for the jittered background refresh interval. Pangolin waits a random duration between min and max so many instances do not hit the upstream at the same moment.

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
Enable AI Gateway Client IP Header	`ENABLE_AI_GATEWAY_CLIENT_IP_HEADER`	`server.enable_ai_gateway_client_ip_header`

About

Manage Pangolin

Self-host Pangolin

Development

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

Logs Database

ACME Configuration

AI Model Catalog

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

​Logs Database

​ACME Configuration

​AI Model Catalog

​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

Logs Database

ACME Configuration

AI Model Catalog

Environment Variables