# Tailscale

Surge Mac 6.7.0 now supports Tailscale as a proxy policy.

With this feature, Surge can join your Tailscale tailnet directly and route selected traffic through Tailscale peers using the existing Surge rule system. You can use Tailscale IPs, and tailnet-only services together with Surge policies, policy groups, DNS handling, traffic logging, and rule-based routing.

* It is still an early beta version and may encounter various crashes and issues.
* Only TCP-based Tailscale control and DERP paths are supported. Direct UDP path support is not yet implemented.
* MagicDNS has already been implemented, but requests still need to be sent into the Tailscale policy through the rule system.
* Surge iOS support will be released soon.

## Configuration Example

```ini
[Proxy]
ts-home = tailscale, section-name=Home

[Tailscale Home]
auth-key = tskey-auth-xxxxxxxxxxxxxxxx
```

You can then use the policy in rules:

```ini
[Rule]
IP-CIDR,100.64.0.0/10,ts-home,no-resolve
DOMAIN-SUFFIX,internal.example.ts.net,ts-home
FINAL,DIRECT
```

## Proxy Policy

```ini
ts-home = tailscale, section-name=Home
```

Defines a Surge proxy policy backed by a Tailscale session.

The `underlying-proxy` parameter is supported. If configured, both the Tailscale control server and DERP server will be accessed through this proxy.

`section-name` points to a matching `[Tailscale name]` section. In this example, `section-name=Home` maps to: `[Tailscale Home]`

## Tailscale Section

Defines the Tailscale node configuration used by the policy.

### auth-key

```ini
[Tailscale home]
auth-key = tskey-auth-xxxxxxxxxxxxxxxx
```

The Tailscale auth key used to register this Surge instance into your tailnet.

Create it from the Tailscale admin console:

> Settings -> Keys -> Generate auth key

The `auth-key` is only needed when connecting to the network for the first time. After that, Surge will store the node state, so in subsequent connections, the `auth-key` no longer has any practical meaning.

However, once the `auth-key` is modified, Surge will clear the currently saved state and perform device registration again.

If you want to use the same profile on multiple devices, you can enable the reusable option for this auth-key, so that multiple devices can complete the registration process.

### hostname (Optional)

```ini
[Tailscale home]
hostname = surge-mac
```

Optional. Sets the device name requested from Tailscale.

If omitted, Surge generates a hostname automatically.

### control-url (Optional)

```ini
[Tailscale home]
control-url = https://controlplane.tailscale.com
```

Optional. Overrides the Tailscale control server URL.

Most users should omit this. It is mainly useful for custom control servers such as Headscale.

### mtu (Optional)

```ini
[Tailscale home]
mtu = 1280
```

Optional. Sets the L3 interface MTU used by Surge for this Tailscale session.

The default value is `1280`.

### dns-server (Optional)

```[ini]
[Tailscale home]
dns-server = 8.8.8.8, 1.1.1.1
```

Optional. Sets DNS servers used by this Tailscale policy.

Priority order:

1. User-configured `dns-server`
2. DNS servers received from the Tailscale control plane

Please note that in your Tailscale configuration, there should be a corresponding route table for the DNS address.

### prefer-ipv6 (Optional)

```ini
[Tailscale home]
prefer-ipv6 = true
```

Optional. Prefer IPv6 when both IPv4 and IPv6 are available for DNS resolution.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://kb.nssurge.com/surge-knowledge-base/guidelines/tailscale.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.