Configure Sites

Flags

Almost every setting below can also be set via an environment variable (Env var) or in the config file (Config file key) instead of as a CLI flag. Values are resolved with priority CLI flag > environment variable > config file > default, so a flag always overrides an env var, which always overrides what's saved on disk. This makes environment variables and config files particularly useful for containerized environments where CLI flags are less convenient.

idstringrequired

Site ID generated by Pangolin to identify the client.

Example: 31frd0uzbjvp721

Env var: SITE_ID

Config file key: id

Legacy env var: NEWT_SECRET

secretstringrequired

A unique secret used to authenticate the site with the websocket.

Example: h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6

Env var: SITE_SECRET

Config file key: secret

Legacy env var: NEWT_SECRET

Keep this secret private and secure. It's used for authentication.

endpointstringrequired

The endpoint where the Pangolin server resides for websocket connections.

Example: https://pangolin.example.com

Env var: PANGOLIN_ENDPOINT

Config file key: endpoint

namestring

Site name to use when provisioning with a provisioning key. Supports {{env.VARIABLE_NAME}} templating from the process environment. If omitted, Pangolin assigns a random animal-based name (changeable in the dashboard).

Example: my-edge-site or '{{env.SERIAL_NUMBER}}-edge'

Env var: SITE_NAME

Config file key: name

provisioning-blueprint-filestring

Path to a blueprint YAML file applied once at provisioning (imperative bootstrap). Unlike --blueprint-file, the site does not keep reapplying it, so resources you edit in the dashboard are not overwritten on later runs. See Site provisioning keys.

Example: /path/to/bootstrap.yaml

Env var: PROVISIONING_BLUEPRINT_FILE

Config file key: provisioningBlueprintFile

provisioning-keystring

Provisioning key from Pangolin (alternative to a provisioningKey field inside the config file). The site exchanges it once for site credentials, then persists id and secret to the config file and ignores the key on later runs. This flag is not written into the config file. See Site provisioning keys.

Example: spk_...

Env var: SITE_PROVISIONING_KEY

Config file key: provisioningKey

Legacy env var: NEWT_PROVISIONING_KEY

config-filestring

Path to a JSON file where the site reads and persists settings (endpoint, id, secret, optional provisioningKey, and virtually every other flag below). When you use site provisioning, the site writes id and secret into this file after a successful exchange. See Config File for the default path on each platform.

Example: /var/site.json

Env var: CONFIG_FILE

dnsstring

DNS server to use for resolving the endpoint.

Default: 9.9.9.9

Env var: DNS

Config file key: dns

log-levelstring

The log level to use for the site output.

Options: DEBUG, INFO, WARN, ERROR, FATAL

Default: INFO

Env var: LOG_LEVEL

Config file key: logLevel

ping-intervalstring

Interval for pinging the server.

Default: 15s

Env var: PING_INTERVAL

Config file key: pingInterval

ping-timeoutstring

Timeout for each ping.

Default: 7s

Env var: PING_TIMEOUT

Config file key: pingTimeout

udp-proxy-idle-timeoutstring

Idle timeout for UDP proxied client flows before cleanup.

Default: 90s

Env var: SITE_UDP_PROXY_IDLE_TIMEOUT

Config file key: udpProxyIdleTimeout

Legacy env var: NEWT_UDP_PROXY_IDLE_TIMEOUT

docker-socketstring

Set the Docker socket path for container discovery integration.

Example: /var/run/docker.sock

Env var: DOCKER_SOCKET

Config file key: dockerSocket

docker-enforce-network-validationboolean

Validate the container target is on the same network as the the site process.

Default: false

Env var: DOCKER_ENFORCE_NETWORK_VALIDATION

Config file key: dockerEnforceNetworkValidation

health-filestring

Check if connection to WireGuard server (Pangolin) is ok. Creates a file if ok, removes it if not ok. Can be used with Docker healthcheck to restart the site.

Example: /tmp/healthy

Env var: HEALTH_FILE

Config file key: healthFile

updownstring

Script to be called when targets are added or removed.

Example: /path/to/updown.sh

Env var: UPDOWN_SCRIPT

Config file key: updownScript

blueprint-filestring

Path to a blueprint file that defines Pangolin resources and settings. This mode is declarative: the site keeps applying the file, and it remains the source of truth (dashboard changes can be overwritten on the next apply). For a one-time bootstrap blueprint with provisioning keys, use --provisioning-blueprint-file instead.

Example: /path/to/blueprint.yaml

Env var: BLUEPRINT_FILE

Config file key: blueprintFile

no-cloudboolean

Don't fail over to the cloud when using managed nodes in Pangolin Cloud.

Default: false

Env var: NO_CLOUD

Config file key: noCloud

disable-clientsboolean

Disable clients on the WireGuard interface.

Default: false (clients enabled)

Env var: DISABLE_CLIENTS

Config file key: disableClients

disable-sshboolean

Disable SSH auth daemon and native SSH mode (remote auth daemon integrations still work).

Default: false

Env var: DISABLE_SSH

Config file key: disableSsh

metricsboolean

Enable Prometheus /metrics exporter.

Default: false

Env var: SITE_METRICS_PROMETHEUS_ENABLED

Config file key: metrics

Legacy env var: NEWT_METRICS_PROMETHEUS_ENABLED

otlpboolean

Enable OTLP exporters (metrics/traces) to OTEL_EXPORTER_OTLP_ENDPOINT.

Default: false

Env var: SITE_METRICS_OTLP_ENABLED

Config file key: otlp

Legacy env var: NEWT_METRICS_OTLP_ENABLED

metrics-admin-addrstring

Admin/metrics bind address.

Default: 127.0.0.1:2112

Env var: SITE_ADMIN_ADDR

Config file key: metricsAdminAddr

Legacy env var: NEWT_ADMIN_ADDR

metrics-async-bytesboolean

Enable async bytes counting (background flush; lower hot path overhead).

Default: false

Env var: SITE_METRICS_ASYNC_BYTES

Config file key: metricsAsyncBytes

Legacy env var: NEWT_METRICS_ASYNC_BYTES

pprofboolean

Enable pprof debug endpoints on the admin server.

Default: false

Env var: SITE_PPROF_ENABLED

Config file key: pprof

Legacy env var: NEWT_PPROF_ENABLED

regionstring

Optional region resource attribute for telemetry and metrics.

Example: us-west-2

Env var: SITE_REGION

Config file key: region

Legacy env var: NEWT_REGION

enforce-hc-certboolean

Enforce certificate validation for health checks.

Default: false (accepts any cert)

Env var: ENFORCE_HC_CERT

Config file key: enforceHcCert

tls-client-cert-filestring

Path to client certificate file (PEM/DER format) for mTLS.

Example: /path/to/client.crt

Env var: TLS_CLIENT_CERT

Config file key: tlsClientCertFile

tls-client-keystring

Path to client private key file (PEM/DER format) for mTLS.

Example: /path/to/client.key

Env var: TLS_CLIENT_KEY

Config file key: tlsClientKey

tls-client-castring

Path to CA certificate file for validating remote certificates (can be specified multiple times).

Example: /path/to/ca.crt

Env var: TLS_CLIENT_CAS (comma-separated list)

Config file key: tlsClientCa (array of strings in the config file)

tls-client-certstring

Path to client certificate (PKCS12 format) - DEPRECATED: use --tls-client-cert-file and --tls-client-key instead.

Example: /path/to/client.p12

Env var: TLS_CLIENT_CERT_PKCS12

Config file key: tlsClientCert

ad-pre-shared-keystring

Pre-shared key for auth daemon authentication.

Env var: AD_KEY

Config file key: adPreSharedKey

ad-principals-filestring

Path to the principals file for auth daemon.

Default: /var/run/auth-daemon/principals

Env var: AD_PRINCIPALS_FILE

Config file key: adPrincipalsFile

ad-ca-cert-pathstring

Path to the CA certificate file for auth daemon.

Default: /etc/ssh/ca.pem

Env var: AD_CA_CERT_PATH

Config file key: adCaCertPath

ad-generate-random-passwordboolean

Generate a random password for authenticated users.

Default: false

Env var: AD_GENERATE_RANDOM_PASSWORD

Config file key: adGenerateRandomPassword

versionboolean

Print the Newt (package) version and exit.

show-configboolean

Print the fully resolved configuration (including which source — default, config file, environment, or CLI — each value came from) and exit. Secrets are masked. Useful for confirming what a config file actually loaded.

Default: false

prefer-endpointstring

Prefer this endpoint for the connection (if set, will override the endpoint from the server).

Example: https://preferred.endpoint.com

Config file key: preferEndpoint

interfacestring

Name of the WireGuard interface.

Default: pangolin

Env var: INTERFACE

Config file key: interface

portinteger

Port for the peers to connect to the site on. This can be used to keep a static port open in firewalls instead of default random ports.

Example: 34534

Env var: PORT

Config file key: port

nativeboolean

Use a native WireGuard interface for client tunnels instead of the userspace netstack implementation.

Most users should not use this feature.

Default: false

Env var: USE_NATIVE_INTERFACE

Config file key: native

native-mainboolean

Use a native WireGuard interface for the main tunnel (instead of netstack).

Most users should not use this feature.

Default: false

Env var: USE_NATIVE_MAIN_INTERFACE

Config file key: nativeMain

interface-mainstring

Name of the native main tunnel WireGuard interface (used with --native-main).

Most users should not use this feature.

Default: pangolin

Env var: INTERFACE_MAIN

Config file key: interfaceMain

mtuinteger

MTU for the internal WireGuard interface.

Most users should not use this feature.

Default: 1280

Env var: MTU

Config file key: mtu

Config File

The site can be configured entirely with a JSON config file instead of (or in addition to) CLI flags and environment variables. Almost every flag documented above has a matching camelCase key in this file — see the Config file key on each flag for its exact name.

You can use --config-file or the CONFIG_FILE environment variable to point the site at a specific path. The site also writes to this file: when site provisioning succeeds, the resolved id and secret are persisted here so you don't need to pass --id/--secret (or a provisioning key) on every subsequent run.

Default locations

If --config-file/CONFIG_FILE isn't set, the site reads and writes the config file at a platform-specific default path:

Platform	Default path
macOS	`~/.config/pangolin/site.json`
Windows	`C:\Users\<Username>\.config\pangolin\site.json`
Linux / others	`~/.config/pangolin/site.json`

Example

{
  "endpoint": "https://app.pangolin.net",
  "id": "spmzu8rbpzj1qq6",
  "secret": "f6v61mjutwme2kkydbw3fjo227zl60a2tsf5psw9r25hgae3",
  "name": "my-edge-site",

  "dns": "9.9.9.9",
  "logLevel": "INFO",
  "interface": "pangolin",
  "mtu": 1280,
  "port": 34534,

  "pingInterval": "15s",
  "pingTimeout": "7s",
  "udpProxyIdleTimeout": "90s",

  "disableClients": false,
  "disableSsh": false,
  "noCloud": false,

  "dockerSocket": "unix:///var/run/docker.sock",
  "dockerEnforceNetworkValidation": false,

  "healthFile": "/tmp/healthy",
  "blueprintFile": "/path/to/blueprint.yaml",

  "tlsClientCertFile": "",
  "tlsClientKey": "",
  "tlsClientCa": []
}

You only need to include the keys you want to set — anything omitted falls back to an environment variable, then its built-in default. Run pangolin --show-config to see every resolved setting alongside where it came from (config file, environment, CLI, or default), which is useful for confirming what a config file actually loaded.

Fields like secret, tlsClientKey, and adPreSharedKey are sensitive. Restrict file permissions on the config file accordingly.

Docker Socket Integration

The site can integrate with the Docker socket to provide remote inspection of Docker containers. This allows Pangolin to query and retrieve detailed information about containers running on the site, including metadata, network configuration, port mappings, and more.

Configuration:

You can specify the Docker socket path using the --docker-socket CLI argument or by setting the DOCKER_SOCKET environment variable. If the Docker socket is not available or accessible, the site will gracefully disable Docker integration and continue normal operation.

Supported values include:

Local UNIX socket (default):

You must mount the socket file into the container using a volume, so the site can access it.

unix:///var/run/docker.sock
TCP socket (e.g., via Docker Socket Proxy):

tcp://localhost:2375
HTTP/HTTPS endpoints (e.g., remote Docker APIs):

http://your-host:2375
SSH connections (experimental, requires SSH setup):

ssh://user@host

services:
    pangolin-site:
        image: fosrl/pangolin-cli
        container_name: pangolin-site
        restart: unless-stopped
        volumes:
            - /var/run/docker.sock:/var/run/docker.sock:ro
        environment:
            - PANGOLIN_ENDPOINT=https://example.com
            - SITE_ID=2ix2t8xk22ubpfy
            - SITE_SECRET=nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2
            - DOCKER_SOCKET=unix:///var/run/docker.sock

If the Docker socket is not available or accessible, the site will gracefully disable Docker integration and continue normal operation.

Hostnames vs IPs

When the Docker Socket Integration is used, depending on the network which the site is run with, either the hostname (generally considered the container name) or the IP address of the container will be sent to Pangolin:

Running in Network Mode 'host': IP addresses will be used
Running in Network Mode 'bridge': IP addresses will be used
Running in docker-compose without a network specification: Docker compose creates a network for the compose by default, hostnames will be used
Running on docker-compose with defined network: Hostnames will be used

Docker Enforce Network Validation

When run as a Docker container, the site can validate that the target being provided is on the same network as the site container and only return containers directly accessible by the site. Validation will be carried out against either the hostname/IP Address and the Port number to ensure the running container is exposing the ports to the site.

Validation is false by default. It can be enabled via setting the --docker-enforce-network-validation CLI argument or by setting the DOCKER_ENFORCE_NETWORK_VALIDATION environment variable.

If the site container is run with a network mode of host, this feature will not work. Running in host mode causes the container to share its resources with the host machine, making it impossible to retrieve specific host container information for network validation.

Updown Scripts

You can pass in an updown script for the site to call when it is adding or removing a target:

--updown "python3 test.py"

The script will be called with arguments when a target is added or removed:

python3 test.py add tcp localhost:8556
python3 test.py remove tcp localhost:8556

Returning a string from the script in the format of a target (ip:dst so 10.0.0.1:8080) will override the target and use this value instead to proxy.

You can look at updown.py as a reference script to get started!

mTLS Authentication

The site supports mutual TLS (mTLS) authentication if the server is configured to request a client certificate. You can use either a PKCS12 (.p12/.pfx) file or split PEM files for the client cert, private key, and CA.

Option 1: PKCS12 (Legacy)

This is the original method and still supported.

Requirements:

File must contain:
- Client private key
- Public certificate
- CA certificate
Encrypted .p12 files are not supported

Example:

pangolin \
--id 31frd0uzbjvp721 \
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
--endpoint https://example.com \
--tls-client-cert ./client.p12

Option 2: Split PEM Files (Preferred)

You can now provide separate files for:

--tls-client-cert-file: client certificate (.crt or .pem)
--tls-client-key: client private key (.key or .pem)
--tls-client-ca: CA cert to verify the server (can be specified multiple times)

Example:

pangolin \
--id 31frd0uzbjvp721 \
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
--endpoint https://example.com \
--tls-client-cert-file ./client.crt \
--tls-client-key ./client.key \
--tls-client-ca ./ca.crt

FlagsCopy Anchor Link

Config FileCopy Anchor Link

Default locationsCopy Anchor Link

ExampleCopy Anchor Link

Docker Socket IntegrationCopy Anchor Link

Updown ScriptsCopy Anchor Link

mTLS AuthenticationCopy Anchor Link

Option 1: PKCS12 (Legacy)Copy Anchor Link

Option 2: Split PEM Files (Preferred)Copy Anchor Link

On this page

Flags

Config File

Default locations

Example

Docker Socket Integration

Updown Scripts

mTLS Authentication

Option 1: PKCS12 (Legacy)

Option 2: Split PEM Files (Preferred)