---
title: "Configure Sites"
description: "Configure Newt for connecting to Pangolin sites"
---

import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";

<PangolinCloudTocCta />



## Flags

<ResponseField name="id" type="string" required>
  Newt ID generated by Pangolin to identify the client.

  **Example**: `31frd0uzbjvp721`
</ResponseField>

<ResponseField name="secret" type="string" required>
  A unique secret used to authenticate the client ID with the websocket.

  **Example**: `h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6`

  <Warning>
  Keep this secret private and secure. It's used for authentication.
  </Warning>
</ResponseField>

<ResponseField name="endpoint" type="string" required>
  The endpoint where the Pangolin server resides for websocket connections.

  **Example**: `https://pangolin.example.com`
</ResponseField>

<ResponseField name="name" type="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'`
</ResponseField>

<ResponseField name="provisioning-blueprint-file" type="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](/manage/sites/site-provisioning).

  **Example**: `/path/to/bootstrap.yaml`
</ResponseField>

<ResponseField name="provisioning-key" type="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](/manage/sites/site-provisioning).

  **Example**: `spk_...`
</ResponseField>

<ResponseField name="config-file" type="string">
  Path to a JSON file where Newt reads and persists settings (`endpoint`, `id`, `secret`, optional `provisioningKey`, and other options). When you use [site provisioning](/manage/sites/site-provisioning), Newt writes `id` and `secret` into this file after a successful exchange.

  **Example**: `/var/newt.json`
</ResponseField>

<ResponseField name="port" type="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**: `34534`
</ResponseField>

<ResponseField name="mtu" type="integer">
  MTU for the internal WireGuard interface.

  **Default**: `1280`
</ResponseField>

<ResponseField name="dns" type="string">
  DNS server to use for resolving the endpoint.

  **Default**: `9.9.9.9`
</ResponseField>

<ResponseField name="log-level" type="string">
  The log level to use for Newt output.

  **Options**: `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`

  **Default**: `INFO`
</ResponseField>

<ResponseField name="ping-interval" type="string">
  Interval for pinging the server.

  **Default**: `3s`
</ResponseField>

<ResponseField name="ping-timeout" type="string">
  Timeout for each ping.

  **Default**: `5s`
</ResponseField>

<ResponseField name="docker-socket" type="string">
  Set the Docker socket path for container discovery integration.

  **Example**: `/var/run/docker.sock`
</ResponseField>

<ResponseField name="docker-enforce-network-validation" type="boolean">
  Validate the container target is on the same network as the Newt process.

  **Default**: `false`
</ResponseField>

<ResponseField name="health-file" type="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/healthy`
</ResponseField>

<ResponseField name="updown" type="string">
  Script to be called when targets are added or removed.

  **Example**: `/path/to/updown.sh`
</ResponseField>

<ResponseField name="blueprint-file" type="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.yaml`
</ResponseField>

<ResponseField name="no-cloud" type="boolean">
  Don't fail over to the cloud when using managed nodes in Pangolin Cloud.

  **Default**: `false`
</ResponseField>

<ResponseField name="disable-clients" type="boolean">
  Disable clients on the WireGuard interface.

  **Default**: `false` (clients enabled)
</ResponseField>

<ResponseField name="interface" type="string">
  Name of the WireGuard interface.

  **Default**: `newt`
</ResponseField>

<ResponseField name="metrics" type="boolean">
  Enable Prometheus /metrics exporter.

  **Default**: `true`
</ResponseField>

<ResponseField name="otlp" type="boolean">
  Enable OTLP exporters (metrics/traces) to OTEL_EXPORTER_OTLP_ENDPOINT.

  **Default**: `false`
</ResponseField>

<ResponseField name="metrics-admin-addr" type="string">
  Admin/metrics bind address.

  **Default**: `127.0.0.1:2112`
</ResponseField>

<ResponseField name="metrics-async-bytes" type="boolean">
  Enable async bytes counting (background flush; lower hot path overhead).

  **Default**: `false`
</ResponseField>

<ResponseField name="region" type="string">
  Optional region resource attribute for telemetry and metrics.

  **Example**: `us-west-2`
</ResponseField>

<ResponseField name="enforce-hc-cert" type="boolean">
  Enforce certificate validation for health checks.

  **Default**: `false` (accepts any cert)
</ResponseField>

<ResponseField name="tls-client-cert-file" type="string">
  Path to client certificate file (PEM/DER format) for mTLS.

  **Example**: `/path/to/client.crt`
</ResponseField>

<ResponseField name="tls-client-key" type="string">
  Path to client private key file (PEM/DER format) for mTLS.

  **Example**: `/path/to/client.key`
</ResponseField>

<ResponseField name="tls-client-ca" type="string">
  Path to CA certificate file for validating remote certificates (can be specified multiple times).

  **Example**: `/path/to/ca.crt`
</ResponseField>

<ResponseField name="tls-client-cert" type="string">
  Path to client certificate (PKCS12 format) - DEPRECATED: use `--tls-client-cert-file` and `--tls-client-key` instead.

  **Example**: `/path/to/client.p12`
</ResponseField>

<ResponseField name="prefer-endpoint" type="string">
  Prefer this endpoint for the connection (if set, will override the endpoint from the server).

  **Example**: `https://preferred.endpoint.com`
</ResponseField>

## Environment Variables

All CLI arguments can be set using environment variables as an alternative to command line flags. Environment variables are particularly useful when running Newt in containerized environments.

<Note>
When both environment variables and CLI arguments are provided, CLI arguments take precedence.
</Note>

<ResponseField name="PANGOLIN_ENDPOINT" type="string">
  Endpoint of your Pangolin server (equivalent to `--endpoint`)
</ResponseField>

<ResponseField name="NEWT_ID" type="string">
  Newt ID generated by Pangolin (equivalent to `--id`)
</ResponseField>

<ResponseField name="NEWT_SECRET" type="string">
  Newt secret for authentication (equivalent to `--secret`)
</ResponseField>

<ResponseField name="AUTH_DAEMON_ENABLED" type="boolean">
  Enable Newt's built-in auth daemon mode (equivalent to `--auth-daemon`).

  **Default**: `false`
</ResponseField>

<ResponseField name="AD_KEY" type="string">
  Pre-shared key used to authenticate external auth daemons to Newt (equivalent to `--ad-pre-shared-key`)
</ResponseField>

<ResponseField name="NEWT_NAME" type="string">
  Site name when provisioning with a provisioning key (equivalent to `--name`). Supports `{{env.VARIABLE_NAME}}` templating from the environment.
</ResponseField>

<ResponseField name="NEWT_PROVISIONING_KEY" type="string">
  Provisioning key string (equivalent to `--provisioning-key`). See [Site provisioning keys](/manage/sites/site-provisioning).
</ResponseField>

<ResponseField name="PROVISIONING_BLUEPRINT_FILE" type="string">
  Path to a bootstrap-only blueprint file (equivalent to `--provisioning-blueprint-file`). See [Site provisioning keys](/manage/sites/site-provisioning).
</ResponseField>

<ResponseField name="CONFIG_FILE" type="string">
  Path to the JSON config file where Newt loads and persists settings (equivalent to `--config-file`). Use this instead of the default location under the home folder when you want a fixed path (typical for containers and provisioning).

  **Example**: `/var/newt.json`
</ResponseField>

<ResponseField name="PORT" type="integer">
    Port for the peers to connect to Newt on (equivalent to `--port`)
</ResponseField>

<ResponseField name="MTU" type="integer">
  MTU for the internal WireGuard interface (equivalent to `--mtu`)

  **Default**: `1280`
</ResponseField>

<ResponseField name="DNS" type="string">
  DNS server to use for resolving the endpoint (equivalent to `--dns`)

  **Default**: `9.9.9.9`
</ResponseField>

<ResponseField name="BLUEPRINT_FILE" type="string">
  Path to blueprint file to define Pangolin resources and configurations (equivalent to `--blueprint-file`).
</ResponseField>

<ResponseField name="NO_CLOUD" type="boolean">
  Don't fail over to the cloud when using managed nodes in Pangolin Cloud (equivalent to `--no-cloud`).

  **Default**: `false`
</ResponseField>

<ResponseField name="LOG_LEVEL" type="string">
  Log level (equivalent to `--log-level`)

  **Default**: `INFO`
</ResponseField>

<ResponseField name="DOCKER_SOCKET" type="string">
  Path to Docker socket for container discovery (equivalent to `--docker-socket`)
</ResponseField>

<ResponseField name="PING_INTERVAL" type="string">
  Interval for pinging the server (equivalent to `--ping-interval`)

  **Default**: `3s`
</ResponseField>

<ResponseField name="PING_TIMEOUT" type="string">
  Timeout for each ping (equivalent to `--ping-timeout`)

  **Default**: `5s`
</ResponseField>

<ResponseField name="UPDOWN_SCRIPT" type="string">
  Path to updown script for target add/remove events (equivalent to `--updown`)
</ResponseField>

<ResponseField name="DOCKER_ENFORCE_NETWORK_VALIDATION" type="boolean">
  Validate container targets are on same network (equivalent to `--docker-enforce-network-validation`)

  **Default**: `false`
</ResponseField>

<ResponseField name="HEALTH_FILE" type="string">
  Path to health file for connection monitoring (equivalent to `--health-file`)
</ResponseField>

<ResponseField name="DISABLE_CLIENTS" type="boolean">
  Disable clients on the WireGuard interface (equivalent to `--disable-clients`).

  **Default**: `false`
</ResponseField>

<ResponseField name="INTERFACE" type="string">
  Name of the WireGuard interface (equivalent to `--interface`)

  **Default**: `newt`
</ResponseField>

<ResponseField name="NEWT_METRICS_PROMETHEUS_ENABLED" type="boolean">
  Enable Prometheus /metrics exporter (equivalent to `--metrics`).

  **Default**: `true`
</ResponseField>

<ResponseField name="NEWT_METRICS_OTLP_ENABLED" type="boolean">
  Enable OTLP exporters (metrics/traces) to OTEL_EXPORTER_OTLP_ENDPOINT (equivalent to `--otlp`).

  **Default**: `false`
</ResponseField>

<ResponseField name="NEWT_ADMIN_ADDR" type="string">
  Admin/metrics bind address (equivalent to `--metrics-admin-addr`).

  **Default**: `127.0.0.1:2112`
</ResponseField>

<ResponseField name="NEWT_METRICS_ASYNC_BYTES" type="boolean">
  Enable async bytes counting (background flush; lower hot path overhead, equivalent to `--metrics-async-bytes`).

  **Default**: `false`
</ResponseField>

<ResponseField name="NEWT_REGION" type="string">
  Optional region resource attribute for telemetry and metrics (equivalent to `--region`).
</ResponseField>

<ResponseField name="ENFORCE_HC_CERT" type="boolean">
  Enforce certificate validation for health checks (equivalent to `--enforce-hc-cert`).

  **Default**: `false`
</ResponseField>

<ResponseField name="TLS_CLIENT_CERT" type="string">
  Path to client certificate file (PEM/DER format) for mTLS (equivalent to `--tls-client-cert-file`)
</ResponseField>

<ResponseField name="TLS_CLIENT_KEY" type="string">
  Path to client private key file (PEM/DER format) for mTLS (equivalent to `--tls-client-key`)
</ResponseField>

<ResponseField name="TLS_CLIENT_CAS" type="string">
  Comma-separated list of CA certificate file paths for validating remote certificates (equivalent to multiple `--tls-client-ca` flags)
</ResponseField>

<ResponseField name="TLS_CLIENT_CERT_PKCS12" type="string">
  Path to client certificate (PKCS12 format) - DEPRECATED: use `TLS_CLIENT_CERT` and `TLS_CLIENT_KEY` instead
</ResponseField>

## Loading secrets from files

You can use `--config-file` or the `CONFIG_FILE` environment variable to set the path of the config file where Newt stores credentials and other settings between runs.

```
$ cat ~/.config/newt-client/config.json
{
  "id": "spmzu8rbpzj1qq6",
  "secret": "f6v61mjutwme2kkydbw3fjo227zl60a2tsf5psw9r25hgae3",
  "endpoint": "https://app.pangolin.net",
  "tlsClientCert": ""
}
```

This file is also written to when newt first starts up. So you do not need to run every time with --id and secret if you have run it once!

Default locations:

- **macOS**: `~/Library/Application Support/newt-client/config.json`
- **Windows**: `%PROGRAMDATA%\newt\newt-client\config.json`
- **Linux/Others**: `~/.config/newt-client/config.json`

## 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`


```yaml
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
```

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

**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.

<Warning>
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.
</Warning>

## Updown Scripts

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

```bash
--updown "python3 test.py"
```

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

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

<Info>
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.
</Info>

<Note>
You can look at `updown.py` as a reference script to get started!
</Note>

## 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)

<Note>
This is the original method and still supported.
</Note>

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

**Example:**

```bash
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:**

```bash
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
```

## NAT Traversal Tweaks

Newt supports NAT traversal to allow clients to connect directly to Newt sites without relaying through the Pangolin server, improving performance and reducing latency.

In some environment depending on the NAT type and firewall, you may need to tweak some settings to get optimal connectivity in the firewall itself. Take a look at [these docs](https://tailscale.com/kb/1361/firewall) for some firewall changes you might be able to make.

Another option is to keep newt listening for client connections on a static port. This allows you to open a specific port in your firewall for Newt client connections instead of random high ports. You can do this by setting the `--port` flag or `PORT` environment variable and then opening this port in the your firewall to DNAT to Newt.
