Update the site settings; complete backhaul docs

2026-10-21 20:19:11 +02:00 · 2026-07-02 18:18:40 -04:00
parent 80db7d514c
commit d63c5175c2
3 changed files with 396 additions and 250 deletions
@@ -9,10 +9,18 @@ import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";

 ## Flags

+<Note>
+Almost every setting below can also be set via an environment variable (**Env var**) or in the [config file](#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.
+</Note>
+
 <ResponseField name="id" type="string" required>
  Newt ID generated by Pangolin to identify the client.

  **Example**: `31frd0uzbjvp721`
+
+  **Env var**: `NEWT_ID`
+
+  **Config file key**: `id`
 </ResponseField>

 <ResponseField name="secret" type="string" required>
@@ -20,6 +28,10 @@ import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";

  **Example**: `h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6`

+  **Env var**: `NEWT_SECRET`
+
+  **Config file key**: `secret`
+
  <Warning>
  Keep this secret private and secure. It's used for authentication.
  </Warning>
@@ -29,48 +41,108 @@ import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
  The endpoint where the Pangolin server resides for websocket connections.

  **Example**: `https://pangolin.example.com`
+
+  **Env var**: `PANGOLIN_ENDPOINT`
+
+  **Config file key**: `endpoint`
 </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'`
+
+  **Env var**: `NEWT_NAME`
+
+  **Config file key**: `name`
 </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`
+
+  **Env var**: `PROVISIONING_BLUEPRINT_FILE`
+
+  **Config file key**: `provisioningBlueprintFile`
 </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_...`
+
+  **Env var**: `NEWT_PROVISIONING_KEY`
+
+  **Config file key**: `provisioningKey`
 </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.
+  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](/manage/sites/site-provisioning), Newt writes `id` and `secret` into this file after a successful exchange. See [Config File](#config-file) for the default path on each platform.

  **Example**: `/var/newt.json`
+
+  **Env var**: `CONFIG_FILE`
 </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`
+
+  **Env var**: `PORT`
+
+  **Config file key**: `port`
+</ResponseField>
+
+<ResponseField name="native" type="boolean">
+  Use a native WireGuard interface for client tunnels instead of the userspace netstack implementation.
+
+  **Default**: `false`
+
+  **Env var**: `USE_NATIVE_INTERFACE`
+
+  **Config file key**: `native`
+</ResponseField>
+
+<ResponseField name="native-main" type="boolean">
+  Use a native WireGuard interface for the main tunnel (instead of netstack).
+
+  **Default**: `false`
+
+  **Env var**: `USE_NATIVE_MAIN_INTERFACE`
+
+  **Config file key**: `nativeMain`
+</ResponseField>
+
+<ResponseField name="interface-main" type="string">
+  Name of the native main tunnel WireGuard interface (used with `--native-main`).
+
+  **Default**: `newt`
+
+  **Env var**: `INTERFACE_MAIN`
+
+  **Config file key**: `interfaceMain`
 </ResponseField>

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

  **Default**: `1280`
+
+  **Env var**: `MTU`
+
+  **Config file key**: `mtu`
 </ResponseField>

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

  **Default**: `9.9.9.9`
+
+  **Env var**: `DNS`
+
+  **Config file key**: `dns`
 </ResponseField>

 <ResponseField name="log-level" type="string">
@@ -79,401 +151,356 @@ import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
  **Options**: `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`

  **Default**: `INFO`
+
+  **Env var**: `LOG_LEVEL`
+
+  **Config file key**: `logLevel`
 </ResponseField>

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

  **Default**: `15s`
+
+  **Env var**: `PING_INTERVAL`
+
+  **Config file key**: `pingInterval`
 </ResponseField>

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

  **Default**: `7s`
+
+  **Env var**: `PING_TIMEOUT`
+
+  **Config file key**: `pingTimeout`
 </ResponseField>

 <ResponseField name="udp-proxy-idle-timeout" type="string">
  Idle timeout for UDP proxied client flows before cleanup.

  **Default**: `90s`
+
+  **Env var**: `NEWT_UDP_PROXY_IDLE_TIMEOUT`
+
+  **Config file key**: `udpProxyIdleTimeout`
 </ResponseField>

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

  **Example**: `/var/run/docker.sock`
+
+  **Env var**: `DOCKER_SOCKET`
+
+  **Config file key**: `dockerSocket`
 </ResponseField>

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

  **Default**: `false`
+
+  **Env var**: `DOCKER_ENFORCE_NETWORK_VALIDATION`
+
+  **Config file key**: `dockerEnforceNetworkValidation`
 </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`
+
+  **Env var**: `HEALTH_FILE`
+
+  **Config file key**: `healthFile`
 </ResponseField>

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

  **Example**: `/path/to/updown.sh`
+
+  **Env var**: `UPDOWN_SCRIPT`
+
+  **Config file key**: `updownScript`
 </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`
+
+  **Env var**: `BLUEPRINT_FILE`
+
+  **Config file key**: `blueprintFile`
 </ResponseField>

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

  **Default**: `false`
+
+  **Env var**: `NO_CLOUD`
+
+  **Config file key**: `noCloud`
 </ResponseField>

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

  **Default**: `false` (clients enabled)
+
+  **Env var**: `DISABLE_CLIENTS`
+
+  **Config file key**: `disableClients`
 </ResponseField>

 <ResponseField name="disable-ssh" type="boolean">
  Disable SSH auth daemon and native SSH mode (remote auth daemon integrations still work).

  **Default**: `false`
+
+  **Env var**: `DISABLE_SSH`
+
+  **Config file key**: `disableSsh`
 </ResponseField>

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

  **Default**: `newt`
+
+  **Env var**: `INTERFACE`
+
+  **Config file key**: `interface`
 </ResponseField>

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

  **Default**: `false`
+
+  **Env var**: `NEWT_METRICS_PROMETHEUS_ENABLED`
+
+  **Config file key**: `metrics`
 </ResponseField>

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

  **Default**: `false`
+
+  **Env var**: `NEWT_METRICS_OTLP_ENABLED`
+
+  **Config file key**: `otlp`
 </ResponseField>

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

  **Default**: `127.0.0.1:2112`
+
+  **Env var**: `NEWT_ADMIN_ADDR`
+
+  **Config file key**: `metricsAdminAddr`
 </ResponseField>

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

  **Default**: `false`
+
+  **Env var**: `NEWT_METRICS_ASYNC_BYTES`
+
+  **Config file key**: `metricsAsyncBytes`
 </ResponseField>

 <ResponseField name="pprof" type="boolean">
  Enable pprof debug endpoints on the admin server.

  **Default**: `false`
+
+  **Env var**: `NEWT_PPROF_ENABLED`
+
+  **Config file key**: `pprof`
 </ResponseField>

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

  **Example**: `us-west-2`
+
+  **Env var**: `NEWT_REGION`
+
+  **Config file key**: `region`
 </ResponseField>

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

  **Default**: `false` (accepts any cert)
+
+  **Env var**: `ENFORCE_HC_CERT`
+
+  **Config file key**: `enforceHcCert`
 </ResponseField>

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

  **Example**: `/path/to/client.crt`
+
+  **Env var**: `TLS_CLIENT_CERT`
+
+  **Config file key**: `tlsClientCertFile`
 </ResponseField>

 <ResponseField name="tls-client-key" type="string">
  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`
 </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`
+
+  **Env var**: `TLS_CLIENT_CAS` (comma-separated list)
+
+  **Config file key**: `tlsClientCa` (array of strings in the config file)
 </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`
+
+  **Env var**: `TLS_CLIENT_CERT_PKCS12`
+
+  **Config file key**: `tlsClientCert`
 </ResponseField>

 <ResponseField name="ad-pre-shared-key" type="string">
  Pre-shared key for auth daemon authentication.
+
+  **Env var**: `AD_KEY`
+
+  **Config file key**: `adPreSharedKey`
 </ResponseField>

 <ResponseField name="ad-principals-file" type="string">
  Path to the principals file for auth daemon.

  **Default**: `/var/run/auth-daemon/principals`
+
+  **Env var**: `AD_PRINCIPALS_FILE`
+
+  **Config file key**: `adPrincipalsFile`
 </ResponseField>

 <ResponseField name="ad-ca-cert-path" type="string">
  Path to the CA certificate file for auth daemon.

  **Default**: `/etc/ssh/ca.pem`
+
+  **Env var**: `AD_CA_CERT_PATH`
+
+  **Config file key**: `adCaCertPath`
 </ResponseField>

 <ResponseField name="ad-generate-random-password" type="boolean">
  Generate a random password for authenticated users.

  **Default**: `false`
+
+  **Env var**: `AD_GENERATE_RANDOM_PASSWORD`
+
+  **Config file key**: `adGenerateRandomPassword`
 </ResponseField>

 <ResponseField name="version" type="boolean">
  Print the Newt version and exit.
 </ResponseField>

+<ResponseField name="show-config" type="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`
+</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`
+
+  **Config file key**: `preferEndpoint`
 </ResponseField>

-## Environment Variables
+## Config File

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

-<Note>
-When both environment variables and CLI arguments are provided, CLI arguments take precedence.
-</Note>
+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](/manage/sites/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.

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

-<ResponseField name="NEWT_ID" type="string">
-  Newt ID generated by Pangolin (equivalent to `--id`)
-</ResponseField>
+If `--config-file`/`CONFIG_FILE` isn't set, Newt reads and writes the config file at a platform-specific default path:

-<ResponseField name="NEWT_SECRET" type="string">
-  Newt secret for authentication (equivalent to `--secret`)
-</ResponseField>
+| 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` |

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

-<ResponseField name="AD_PRINCIPALS_FILE" type="string">
-  Path to the principals file for auth daemon (equivalent to `--ad-principals-file`).
-
-  **Default**: `/var/run/auth-daemon/principals`
-</ResponseField>
-
-<ResponseField name="AD_CA_CERT_PATH" type="string">
-  Path to the CA certificate file for auth daemon (equivalent to `--ad-ca-cert-path`).
-
-  **Default**: `/etc/ssh/ca.pem`
-</ResponseField>
-
-<ResponseField name="AD_GENERATE_RANDOM_PASSWORD" type="boolean">
-  Generate a random password for authenticated users (equivalent to `--ad-generate-random-password`).
-
-  **Default**: `false`
-</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**: `15s`
-</ResponseField>
-
-<ResponseField name="PING_TIMEOUT" type="string">
-  Timeout for each ping (equivalent to `--ping-timeout`)
-
-  **Default**: `7s`
-</ResponseField>
-
-<ResponseField name="NEWT_UDP_PROXY_IDLE_TIMEOUT" type="string">
-  Idle timeout for UDP proxied client flows before cleanup (equivalent to `--udp-proxy-idle-timeout`).
-
-  **Default**: `90s`
-</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="DISABLE_SSH" type="boolean">
-  Disable SSH auth daemon and native SSH mode (equivalent to `--disable-ssh`).
-
-  **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**: `false`
-</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_PPROF_ENABLED" type="boolean">
-  Enable pprof debug endpoints on the admin server (equivalent to `--pprof`).
-
-  **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
+```json
 {
+  "endpoint": "https://app.pangolin.net",
  "id": "spmzu8rbpzj1qq6",
  "secret": "f6v61mjutwme2kkydbw3fjo227zl60a2tsf5psw9r25hgae3",
-  "endpoint": "https://app.pangolin.net",
-  "tlsClientCert": ""
+  "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": []
 }
 ```

-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!
+<Note>
+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.
+</Note>

-Default locations:
-
- **macOS**: `~/Library/Application Support/newt-client/config.json`
- **Windows**: `%PROGRAMDATA%\newt\newt-client\config.json`
- **Linux/Others**: `~/.config/newt-client/config.json`
+<Warning>
+Fields like `secret`, `tlsClientKey`, and `adPreSharedKey` are sensitive. Restrict file permissions on the config file accordingly.
+</Warning>

 ## Docker Socket Integration