# Tailscale daemon configuration file Last validated Jan 8, 2026 > **Warning:** > > The `tailscaled` configuration file support is in alpha and the schema might change in future releases. Tailscale intends to preserve compatibility with earlier versions when possible. If breaking changes occur, a new version designation will be used. You can configure the [Tailscale daemon][kb-tailscaled] (`tailscaled`) using a JSON configuration file instead of command-line flags passed to the [Tailscale CLI][kb-cli]. This approach is useful for headless deployments, containers, Kubernetes, and [infrastructure-as-code workflows][kb-infrastructure-as-code]. ## Basic usage The `tailscaled` configuration file only requires you to set the `version` field manually. The following example shows a minimal configuration example: ```json { "version": "alpha0", "authKey": "tskey-auth-example-XXXXX", "hostname": "my-server", "acceptRoutes": true } ``` To start `tailscaled` with a configuration file, use the `--config` flag: ```shell tailscaled --config=/etc/tailscale/config.json ``` > **Warning:** > > The Tailscale daemon does not automatically discover configuration files. You must specify the path explicitly using the `--config` flag. ## Configuration options The configuration file uses JSON or [HuJSON][xt-hujson] format. The following tables describe all available options. This section organizes all configuration options by category. ### Required options The `version` field is the only required option because all other necessary options have default values. If you omit optional fields, the Tailscale daemon uses the default values. | Option | Type | Description | | --------- | ------ | ----------------------------------------------------------------------------------------------- | | `version` | String | Required. The version of the configuration file schema. The only supported value is `"alpha0"`. | ### Authentication The following configuration options are for authenticating with the Tailscale [control plane][kb-control-data-planes]. | Option | Type | Default | Description | | ----------- | ------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `serverURL` | String | `https://controlplane.tailscale.com` | Specify the URL of a [custom control server][kb-custom-control-server]. | | `authKey` | String | None | Specify an [Auth key][kb-auth-keys] or [OAuth client secret][kb-oauth-clients] for authentication. Prefix with `file:` to read from a file path (for example, `file:/etc/tailscale/authkey`). The daemon re-reads the file each time it authenticates with the [control plane][kb-control-data-planes]. | ### General settings The following configuration options are options for general Tailscale behavior. | Option | Type | Default | Description | | -------------- | ------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `locked` | Boolean | `true` | Set to `true` to prevent configuration changes by using the [`tailscale set`][kb-cli-set] command, ensuring the configuration stays consistent with the file. Set to `false` to allow runtime modifications. | | `enabled` | Boolean | `true` | Specify whether Tailscale should be running. Setting this to `false` has the same effect as running `tailscale down`. | | `hostname` | String | OS hostname | Specify the hostname for the device as displayed in the admin console and used for [MagicDNS][kb-magicdns]. | | `operatorUser` | String | None | Specify a local Unix username allowed to operate `tailscaled` without root privileges. | ### DNS and routing The following configuration options are options for DNS and subnet routing. | Option | Type | Default | Description | | ----------------- | ---------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------- | | `acceptDNS` | Boolean | `true` | Set to `false` to disable using the [DNS configuration][kb-dns] from the tailnet. | | `acceptRoutes` | Boolean | [Platform-dependent][ar-acceptroutes-defaults] | Set to `true` to accept [subnet routes][kb-subnets] advertised by other devices. | | `advertiseRoutes` | Array of Strings | None | An array of [subnet routes][kb-subnets] to advertise to the tailnet. Use the format `[""]`. | | `disableSNAT` | Boolean | `false` | Set to `true` to disable source NAT for traffic to advertised subnet routes. | > **Note:** > > Platform-dependent default values for `acceptRoutes`: > > * Defaults to `true` for Windows, iOS, Android, the macOS App Store variant, and the macOS Standalone variant. > * Defaults to `false` Unix platforms (Linux, BSD, and the macOS open source variant). ### Exit nodes The following configuration options are options for [exit nodes][kb-exit-nodes]. | Option | Type | Default | Description | | ---------------------------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `exitNode` | String | None | [Exit node][kb-exit-nodes] to use. You can use an IP address, stable node ID, or MagicDNS base name. It accepts any value supported by the [`tailscale set --exit-node=`][kb-cli-set] command. | | `allowLANWhileUsingExitNode` | Boolean | `false` | Set to `true` to permit access to the local network (LAN) while routing traffic through an exit node. | > **Tip:** > > You can find the stable node ID of a device in the [Machines](https://login.tailscale.com/admin/machines) of the admin console. ### Features The following configuration options are for enabling or disabling specific Tailscale features. | Option | Type | Default | Description | | ------------------- | ---------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `runSSHServer` | Boolean | `false` | Set to `true` to enable [Tailscale SSH][kb-tailscale-ssh] server. | | `runWebClient` | Boolean | `false` | Set to `true` to enable the Tailscale [web client interface][kb-device-web-interface]. | | `shieldsUp` | Boolean | `false` | Set to `true` to block all incoming connections from other tailnet regardless of access control policies. You might consider this if you only want to permit outbound connections. This is similar to how you can configure [incoming connections in the Tailscale client][kb-client-preferences-incoming-connections]. | | `postureChecking` | Boolean | `false` | Set to `true` to enable [device posture][kb-device-posture] data collection. | | `advertiseServices` | Array of Strings | None | Specify [services][kb-services] to advertise (for example, `["svc:my-api"]`). Used with Tailscale Service virtual IP addresses for high availability. | | `appConnector` | Object | None | [App connector][kb-app-connectors] configuration. Set `{"advertise": true}` to run as an [app connector][kb-app-connectors-setup]. | ### Auto-update The following configuration options are options for automatic updates. | Option | Type | Default | Description | | ------------ | ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `autoUpdate` | Object | None | Auto-update preferences. Set to `check` to enable checking for updates. Set to `apply` to automatically apply updates. For example: `{"check": true, "apply": false}`. | ### Linux-specific options Linux-specific configuration options. | Option | Type | Default | Description | | --------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `netfilterMode` | String | `"on"` | Set the firewall management mode: `"on"`, `"nodivert"`, or `"off"`. This specifies how `tailscaled` manages `iptables`/`nftables` rules on Linux. | | `noStatefulFiltering` | Boolean | `false` | Set to `true` to disable stateful packet filtering for subnet routers and exit nodes. | #### `netfilterMode` values * `on`: Normal operation. In this mode, `tailscaled` creates `iptables`/`nftables` chains and adds a rule to start of the relevant standard chains that jumps into them. For example, it inserts a jump to `ts-input` at the start of the `filter` table `INPUT` chain, to `ts-forward` from `FORWARD`, to `ts-output` from `OUTPUT`, and so on. It also adds a `ts-postrouting` in the `nat` table. * `nodivert`: No divert mode. In this mode, `tailscaled` creates `iptables`/`nftables` chains as usual, but does not send traffic to them. For the system to work correctly, you must configure those rules manually (for example, add a jump from `INPUT` to `ts-input`). This makes it possible to have other rules take effect before the Tailscale rules. Using `nodivert` also means that `tailscaled` won't rewrite the jumps occasionally because this would move the Tailscale rules back to the start. * `off`: In this mode, `tailscaled` does not make any changes to `iptables`/`nftables`. There usually isn't a good reason to use this mode. ### Advanced options The following configuration options are options for advanced use cases, such as customizing the Kubernetes Operators. | Option | Type | Default | Description | | ----------------- | ---------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `staticEndpoints` | Array of Strings | None | Specify an array of additional [WireGuard][kb-wireguard] endpoints to advertise alongside discovered endpoints. Use the format `["
:"]`. Refer to [Kubernetes Operator customization][kb-k8s-static-endpoints] for more information. | ## Schema reference The following schema shows all available options in a single block. Remove all comments before using this in a JSON file, or use [HuJSON][xt-hujson] format to keep them. ```json { "version": "alpha0", // Required. "serverURL": "https://controlplane.tailscale.com", // Optional. "authKey": "", // Optional. "locked": true, // Optional. "enabled": true, // Optional. "hostname": "", // Optional. Default: OS hostname. "operatorUser": "", // Optional. "acceptDNS": , // Optional. Default: platform-dependent. "acceptRoutes": , // Optional. Default: platform-dependent. "advertiseRoutes": [""], // Optional. "disableSNAT": false, // Optional. "exitNode": "", // Optional. "allowLANWhileUsingExitNode": false, // Optional. "runSSHServer": false, // Optional. "runWebClient": false, // Optional. "shieldsUp": false, // Optional. "postureChecking": false, // Optional. "advertiseServices": ["svc:"], // Optional. "appConnector": {"advertise": }, // Optional. "autoUpdate": {"check": , "apply": }, // Optional. "netfilterMode": "on", // Optional (Linux-specific). Values: "on", "nodivert", "off". "noStatefulFiltering": false, // Optional. "staticEndpoints": ["
:"], // Optional. } ``` ## Read configuration from cloud metadata Instead of using a configuration file, you can read configuration options directly from cloud instance metadata. > **Note:** > > Cloud metadata support is limited to Amazon EC2. Support for Google Cloud Platform (GCP), Azure, and [cloud-init][kb-cloud-init] is planned for future releases. To read configuration from an [Amazon EC2][xt-amazon-ec2] instance, store the configuration in the instance's user data and use the special path `vm:user-data`: ```shell tailscaled --config=vm:user-data ``` This tells the `tailscaled` daemon to read the configuration from the EC2 instance metadata service at `http:///latest/user-data`. ## Reload configuration changes The Tailscale daemon reads the configuration file one time at startup and does not automatically monitor it for changes. To apply configuration changes, you have the following options: ### Manually reload the configuration Use the `tailscale debug reload-config` command to reload the configuration file without restarting the daemon: ```shell tailscale debug reload-config ``` This command calls the LocalAPI endpoint `/localapi/v0/reload-config` and applies any changes from the configuration file. ### Restart the daemon Restart `tailscaled` to reload the configuration: ```shell sudo systemctl restart tailscaled ``` > **Note:** > > Automatic configuration file watching for standalone `tailscaled` deployments is not currently supported. If you need this functionality outside of Kubernetes, consider using a file watcher that calls `tailscale debug reload-config` when it detects changes. ## Limitations You can use configuration files on Linux and other Unix-like systems where you run `tailscaled` directly. For macOS, refer to [tailscaled on macOS][xt-tailscaled-macos]. iOS and Android do not support configuration files. [ar-acceptroutes-defaults]: #acceptroutes-defaults [kb-app-connectors]: /docs/features/app-connectors [kb-app-connectors-setup]: /docs/features/app-connectors/how-to/setup [kb-auth-keys]: /docs/features/access-control/auth-keys [kb-cli]: /docs/reference/tailscale-cli [kb-cli-set]: /docs/reference/tailscale-cli#set [kb-cli-set]: /docs/reference/tailscale-cli#set [kb-client-preferences-incoming-connections]: /docs/features/client/manage-preferences#allow-incoming-connections [kb-cloud-init]: /docs/install/with-cloud-init [kb-control-data-planes]: /docs/concepts/control-data-planes [kb-custom-control-server]: /docs/how-to/set-up-custom-control-server [kb-device-posture]: /docs/features/device-posture [kb-device-web-interface]: /docs/features/client/device-web-interface [kb-dns]: /docs/reference/dns-in-tailscale [kb-exit-nodes]: /docs/features/exit-nodes [kb-infrastructure-as-code]: /docs/integration-infrastructure-as-code [kb-k8s-static-endpoints]: /docs/kubernetes-operator/manage-and-configure/configure-static-endpoints [kb-magicdns]: /docs/features/magicdns [kb-oauth-clients]: /docs/features/oauth-clients [kb-services]: /docs/features/services [kb-subnets]: /docs/features/subnet-routers [kb-tailscale-ssh]: /docs/features/tailscale-ssh [kb-tailscaled]: /docs/reference/tailscaled [kb-wireguard]: /docs/concepts/wireguard [xt-amazon-ec2]: https://docs.aws.amazon.com/ec2/ [xt-hujson]: https://github.com/tailscale/hujson [xt-tailscaled-macos]: https://github.com/tailscale/tailscale/wiki/Tailscaled-on-macOS