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.

string

required

Newt ID generated by Pangolin to identify the client.Example: 31frd0uzbjvp721Env var: NEWT_IDConfig file key: id

string

required

A unique secret used to authenticate the client ID with the websocket.Example: h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6Env var: NEWT_SECRETConfig file key: secret

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

string

required

The endpoint where the Pangolin server resides for websocket connections.Example: https://pangolin.example.comEnv var: PANGOLIN_ENDPOINTConfig file key: endpoint

string

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: NEWT_NAMEConfig file key: name

string

Path to a blueprint YAML file applied once at provisioning (imperative bootstrap). Unlike --blueprint-file, Newt 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.yamlEnv var: PROVISIONING_BLUEPRINT_FILEConfig file key: provisioningBlueprintFile

string

Provisioning key from Pangolin (alternative to a provisioningKey field inside the config file). Newt 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: NEWT_PROVISIONING_KEYConfig file key: provisioningKey

string

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

integer

Port for the peers to connect to Newt on. This can be used to keep a static port open in firewalls instead of default random ports.Example: 34534Env var: PORTConfig file key: port

boolean

Use a native WireGuard interface for client tunnels instead of the userspace netstack implementation.Default: falseEnv var: USE_NATIVE_INTERFACEConfig file key: native

boolean

Use a native WireGuard interface for the main tunnel (instead of netstack).Default: falseEnv var: USE_NATIVE_MAIN_INTERFACEConfig file key: nativeMain

string

Name of the native main tunnel WireGuard interface (used with --native-main).Default: newtEnv var: INTERFACE_MAINConfig file key: interfaceMain

integer

MTU for the internal WireGuard interface.Default: 1280Env var: MTUConfig file key: mtu

string

DNS server to use for resolving the endpoint.Default: 9.9.9.9Env var: DNSConfig file key: dns

string

The log level to use for Newt output.Options: DEBUG, INFO, WARN, ERROR, FATALDefault: INFOEnv var: LOG_LEVELConfig file key: logLevel

string

Interval for pinging the server.Default: 15sEnv var: PING_INTERVALConfig file key: pingInterval

string

Timeout for each ping.Default: 7sEnv var: PING_TIMEOUTConfig file key: pingTimeout

string

Idle timeout for UDP proxied client flows before cleanup.Default: 90sEnv var: NEWT_UDP_PROXY_IDLE_TIMEOUTConfig file key: udpProxyIdleTimeout

string

Set the Docker socket path for container discovery integration.Example: /var/run/docker.sockEnv var: DOCKER_SOCKETConfig file key: dockerSocket

boolean

Validate the container target is on the same network as the Newt process.Default: falseEnv var: DOCKER_ENFORCE_NETWORK_VALIDATIONConfig file key: dockerEnforceNetworkValidation

string

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 Newt.Example: /tmp/healthyEnv var: HEALTH_FILEConfig file key: healthFile

string

Script to be called when targets are added or removed.Example: /path/to/updown.shEnv var: UPDOWN_SCRIPTConfig file key: updownScript

string

Path to a blueprint file that defines Pangolin resources and settings. This mode is declarative: Newt 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.yamlEnv var: BLUEPRINT_FILEConfig file key: blueprintFile

boolean

Don’t fail over to the cloud when using managed nodes in Pangolin Cloud.Default: falseEnv var: NO_CLOUDConfig file key: noCloud

boolean

Disable clients on the WireGuard interface.Default: false (clients enabled)Env var: DISABLE_CLIENTSConfig file key: disableClients

boolean

Disable SSH auth daemon and native SSH mode (remote auth daemon integrations still work).Default: falseEnv var: DISABLE_SSHConfig file key: disableSsh

string

Name of the WireGuard interface.Default: newtEnv var: INTERFACEConfig file key: interface

boolean

Enable Prometheus /metrics exporter.Default: falseEnv var: NEWT_METRICS_PROMETHEUS_ENABLEDConfig file key: metrics

boolean

Enable OTLP exporters (metrics/traces) to OTEL_EXPORTER_OTLP_ENDPOINT.Default: falseEnv var: NEWT_METRICS_OTLP_ENABLEDConfig file key: otlp

string

Admin/metrics bind address.Default: 127.0.0.1:2112Env var: NEWT_ADMIN_ADDRConfig file key: metricsAdminAddr

boolean

Enable async bytes counting (background flush; lower hot path overhead).Default: falseEnv var: NEWT_METRICS_ASYNC_BYTESConfig file key: metricsAsyncBytes

boolean

Enable pprof debug endpoints on the admin server.Default: falseEnv var: NEWT_PPROF_ENABLEDConfig file key: pprof

string

Optional region resource attribute for telemetry and metrics.Example: us-west-2Env var: NEWT_REGIONConfig file key: region

boolean

Enforce certificate validation for health checks.Default: false (accepts any cert)Env var: ENFORCE_HC_CERTConfig file key: enforceHcCert

string

Path to client certificate file (PEM/DER format) for mTLS.Example: /path/to/client.crtEnv var: TLS_CLIENT_CERTConfig file key: tlsClientCertFile

string

Path to client private key file (PEM/DER format) for mTLS.Example: /path/to/client.keyEnv var: TLS_CLIENT_KEYConfig file key: tlsClientKey

string

Path to CA certificate file for validating remote certificates (can be specified multiple times).Example: /path/to/ca.crtEnv var: TLS_CLIENT_CAS (comma-separated list)Config file key: tlsClientCa (array of strings in the config file)

string

Path to client certificate (PKCS12 format) - DEPRECATED: use --tls-client-cert-file and --tls-client-key instead.Example: /path/to/client.p12Env var: TLS_CLIENT_CERT_PKCS12Config file key: tlsClientCert

string

Pre-shared key for auth daemon authentication.Env var: AD_KEYConfig file key: adPreSharedKey

string

Path to the principals file for auth daemon.Default: /var/run/auth-daemon/principalsEnv var: AD_PRINCIPALS_FILEConfig file key: adPrincipalsFile

string

Path to the CA certificate file for auth daemon.Default: /etc/ssh/ca.pemEnv var: AD_CA_CERT_PATHConfig file key: adCaCertPath

boolean

Generate a random password for authenticated users.Default: falseEnv var: AD_GENERATE_RANDOM_PASSWORDConfig file key: adGenerateRandomPassword

boolean

Print the Newt version and exit.

boolean

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

string

Prefer this endpoint for the connection (if set, will override the endpoint from the server).Example: https://preferred.endpoint.comConfig file key: preferEndpoint

Config File

Newt 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 Newt at a specific path. Newt 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, Newt reads and writes the config file at a platform-specific default path:

Platform	Default path
macOS	`~/Library/Application Support/newt-client/config.json`
Windows	`%PROGRAMDATA%\newt\newt-client\config.json`
Linux / others	`~/.config/newt-client/config.json`

Example

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

  "dns": "9.9.9.9",
  "logLevel": "INFO",
  "interface": "newt",
  "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 newt --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

Newt 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 Newt client, 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, Newt 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 Newt 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:
    newt:
        image: fosrl/newt
        container_name: newt
        restart: unless-stopped
        volumes:
            - /var/run/docker.sock:/var/run/docker.sock:ro
        environment:
            - PANGOLIN_ENDPOINT=https://example.com
            - NEWT_ID=2ix2t8xk22ubpfy
            - NEWT_SECRET=nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2
            - DOCKER_SOCKET=unix:///var/run/docker.sock

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

Hostnames vs IPs When the Docker Socket Integration is used, depending on the network which Newt 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, Newt can validate that the target being provided is on the same network as the Newt container and only return containers directly accessible by Newt. 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 Newt. 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 Newt 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 Newt 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

Newt 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:

newt \
--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:

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

About

Manage Pangolin

Self-host Pangolin

Development

Flags

Config File

Default locations

Example

Docker Socket Integration

Updown Scripts

mTLS Authentication

Option 1: PKCS12 (Legacy)

Option 2: Split PEM Files (Preferred)

​Flags

​Config File

​Default locations

​Example

​Docker Socket Integration

​Updown Scripts

​mTLS Authentication

​Option 1: PKCS12 (Legacy)

​Option 2: Split PEM Files (Preferred)

Flags

Config File

Default locations

Example

Docker Socket Integration

Updown Scripts

mTLS Authentication

Option 1: PKCS12 (Legacy)

Option 2: Split PEM Files (Preferred)