Tailscale iOS 5.20.0+ Mac 6.7.0+

This document describes the Tailscale policy implemented by Surge, including its profile syntax, configuration fields, routing behavior, DNS integration, exit-node support, connection testing, lifecycle, and diagnostics.

Important: A Tailscale policy in Surge is an application-level outbound policy. It is not a replacement for the system Tailscale client and does not turn every connection on the device into tailnet traffic. Only traffic selected by Surge rules or by an explicit policy choice is sent through this Tailscale session.

1. Overview

The Surge Tailscale policy joins a tailnet as an ephemeral node and exposes that tailnet as a Surge proxy policy. It supports both TCP and UDP traffic selected by Surge. Internally, Surge performs the following work:

1. Registers the node with the configured Tailscale control server.
2. Receives the node, peer, route, DNS, and DERP configuration from the control plane.
3. Creates WireGuard tunnels to authorized peers.
4. Discovers direct UDP paths where possible and uses DERP relay paths when direct connectivity is unavailable.
5. Routes packets to the peer whose allowed route best matches the destination.
6. Resolves MagicDNS names and control-plane DNS records inside the Tailscale policy.

This design makes it possible to use a tailnet node, service, subnet route, or exit node from Surge without installing a separate system VPN tunnel.

Supported use cases

• Accessing services hosted on other tailnet nodes.
• Accessing subnets advertised by authorized Tailscale subnet routers.
• Resolving and connecting to MagicDNS names.
• Sending Surge-selected traffic through an authorized Tailscale exit node.
• Chaining Tailscale control and DERP traffic through another Surge policy.
• Using a Tailscale policy in a policy group, rule, or manual policy selection.

Scope and limitations

• The policy handles outbound traffic selected by Surge. It does not advertise this device as a subnet router or exit node.
• It does not expose inbound services from the Surge device to the tailnet.
• Interactive browser login is not implemented. The configured auth key must allow registration to complete without interactive authorization.
• A control server still determines ACLs, peer visibility, routes, DNS settings, exit-node availability, and node authorization.
• A route advertised by a peer is usable only when the control plane delivers that route to this node.

2. Prerequisites

Before configuring the policy, prepare the following:

1. A Tailscale or compatible control server account.
2. An auth key that can register a node without interactive login. A preauthorized key is recommended.
3. Any required ACL, subnet-route, or exit-node approvals in the control plane.
4. A Surge profile in which the policy can be declared.

Treat the auth key as a secret. Anyone who obtains a valid reusable key may be able to add a node to the associated tailnet, subject to the key's server-side restrictions.

3. Quick Start

Add a policy declaration to [Proxy], then add a matching [Tailscale <name>] section.

[Proxy]
My Tailnet = tailscale, section-name=my-tailnet

[Tailscale my-tailnet]
auth-key = tskey-auth-example
hostname = surge-mac

The value of section-name must exactly match the suffix of the corresponding Tailscale section. In the example above, both values are my-tailnet.

After the profile is applied, select My Tailnet directly or reference it from rules:

[Rule]
DOMAIN-SUFFIX,example-tailnet.ts.net,My Tailnet
IP-CIDR,100.64.0.0/10,My Tailnet,no-resolve

The actual MagicDNS suffix and tailnet address ranges are assigned by the control plane. Use the names and routes shown by your tailnet rather than copying the example values blindly.

4. Configuration Model

A complete configuration consists of two parts:

• A policy line in [Proxy], which defines how Surge exposes and tests the policy.
• A named [Tailscale <section-name>] section, which defines the Tailscale node and data plane.

4.1 Policy declaration

[Proxy]
<Policy Name> = tailscale, section-name=<Tailscale Section Name>[, option=value ...]

Example:

[Proxy]
Office Tailnet = tailscale, section-name=office, test-timeout=8

4.2 Tailscale section

[Tailscale office]
auth-key = tskey-auth-example
hostname = surge-office

Section names are profile identifiers. They do not have to match the hostname registered with the control server.

5. Policy-Line Fields

The following policy-line fields are directly relevant to a Tailscale policy.

section-name

This field is mandatory. A missing section-name makes the policy invalid. The referenced section must exist and contain a valid auth-key.

underlying-proxy

By default, control-plane, DERP, STUN, and direct peer-path traffic originate through DIRECT.

When underlying-proxy is configured:

• Control-plane connections use that policy.
• DERP relay connections use that policy.
• Direct physical UDP sockets for peer-to-peer paths are disabled.
• Peer traffic therefore uses DERP relay transport rather than a direct UDP path.

This behavior prevents accidental bypass of the requested underlying policy. It also means that a chained Tailscale policy usually has higher latency and depends on DERP availability.

Example:

[Proxy]
Tailnet via Upstream = tailscale, section-name=tailnet, underlying-proxy=Upstream Proxy

Avoid a dependency loop in which the underlying policy eventually selects the same Tailscale policy.

test-url

An explicit test-url always selects the standard HTTP URL-test path. If no exit node or advertised route can reach that URL, the test fails even when tailnet peer connectivity itself is working.

For a policy without an exit node, either:

• omit test-url and let Surge use the native Tailscale connectivity probe; or
• use a URL hosted on an address reachable through the tailnet.

test-timeout

test-timeout is expressed in seconds and overrides the global proxy test timeout for this policy. If neither is configured, the default is 5 seconds.

The configured timeout remains the limit for the actual probe or HTTP operation. Surge additionally allows up to 10 seconds for Tailscale initialization, including control registration, netmap acquisition, DERP setup, and the first WireGuard handshake. For example, test-timeout=5 may take up to approximately 15 seconds before the overall operation is declared timed out.

6. Tailscale Section Fields

The current parser may ignore an unrecognized key, but this is not a supported extension mechanism. A malformed line or invalid value for a recognized key makes the profile invalid. Use only documented fields.

6.1 auth-key

auth-key = tskey-auth-example

The field is required. Surge sends it when registering the node. The implementation does not open an authorization URL, so a key that requires an interactive approval flow cannot complete registration inside Surge.

Recommended server-side restrictions include:

• short expiration;
• single use unless reuse is required;
• preauthorization;
• appropriate tags and ACL restrictions.

The key is omitted or masked when Surge exports a profile without sensitive data.

Surge stores the Tailscale machine identity in a local state file selected using a hash of the auth key. Reusing the same auth key and profile therefore allows the stored identity to survive idle shutdowns and application restarts. Changing the auth key selects a different state file and normally creates a different node identity.

6.2 control-url

control-url = https://controlplane.tailscale.com

Use this field for the standard Tailscale control plane or a compatible service such as a privately operated control server. It must parse as a URL.

The default is:

https://controlplane.tailscale.com

HTTPS is strongly recommended. The initial server-key retrieval is protected with HTTPS even when an http control URL is supplied, while subsequent transport behavior follows the configured control URL. The server must support the control protocol expected by this implementation.

6.3 hostname

hostname = surge-macbook

This is the node hostname sent during registration. If omitted, Surge uses a platform-derived name such as surge-macos and converts it to lowercase.

The registered DNS name displayed by MagicDNS may include an additional tailnet suffix assigned by the control plane.

6.4 derp-only

derp-only = true

The default is false. When enabled, Surge deliberately uses DERP relay transport for all encrypted peer traffic even when no underlying-proxy is configured and the effective underlying policy is DIRECT.

In DERP-only mode:

• no physical peer-to-peer UDP sockets are opened;
• STUN netcheck and direct endpoint discovery do not run;
• direct-path discovery pings and direct-path heartbeats are disabled;
• previously learned direct-path state is not used for packet transmission; and
• control-plane and DERP connections still use the effective underlying policy normally.

For example, with derp-only = true and no underlying-proxy, the control and DERP connections go out through DIRECT, but peer WireGuard packets remain inside DERP relay connections.

Configuring a non-DIRECT underlying-proxy already makes the effective transport DERP-only. This field is useful when the surrounding connections should remain direct but peer-to-peer UDP must not be attempted.

6.5 exit-node

exit-node = none

Supported modes:

• none: Disable exit-node routing. This is the default.
• auto: Select an exit node only when exactly one usable candidate is present.
• An explicit selector: Select one peer by stable ID, full DNS name, short DNS name, or tailnet IP address.

Names are matched case-insensitively. A trailing dot on a DNS name is ignored. A short name means the first label of the full DNS name.

Explicit examples:

exit-node = office-exit.example-tailnet.ts.net

exit-node = office-exit

exit-node = 100.100.10.20

An explicit selector must match exactly one usable peer. Surge does not silently fall back to another exit node when the selected peer is missing or offline.

See Exit-Node Routing for the full selection logic.

6.6 idle-keepalive

idle-keepalive = 600

This setting controls how long Surge keeps an unused Tailscale networking session alive after its last active TCP connection or UDP mapping closes.

• Positive value: Tear down networking after that many idle seconds.
• 0 or negative value: Keep the session running continuously.
• Default: 600 seconds.

The idle monitor checks periodically, so teardown may occur slightly after the exact threshold. Idle teardown closes control and DERP connections and releases peer tunnels and routes, but preserves the local key state and layer-3 session objects. The next connection starts networking again.

Use idle-keepalive = 0 when low first-packet latency is more important than background resource usage.

6.7 prefer-ipv6

prefer-ipv6 = true

When both IPv4 and IPv6 are available, this setting makes the layer-3 session and DNS result selection prefer IPv6. It does not create IPv6 connectivity by itself; the local node, destination peer, route, and underlying network must all provide the necessary IPv6 support.

6.8 dns-server

dns-server = 100.100.100.100

Multiple resolvers are comma-separated:

dns-server = 100.100.100.100, 10.0.0.53

Accepted entries are:

• a plain IPv4 or IPv6 address;
• an IP address with a port in Surge's supported address-and-port syntax;

IPv4 multicast addresses are rejected. Encrypted DNS URLs such as DoH, DoQ, or DoT URLs do not belong in this field.

When this field is present, it overrides the resolver list received from the Tailscale control plane. Control-provided search domains and locally synthesized MagicDNS records are still applied.

The selected resolver must be reachable through this Tailscale policy's route table. For example, a resolver at a tailnet IP requires an authorized peer route for that IP. A custom resolver that is not routable through the policy causes lookup failures.

6.9 mtu

mtu = 1280

Valid values are 576 through 1420. The default is 1280.

Packets larger than the configured MTU are dropped by the Tailscale layer-3 session. The default is conservative and works well across direct UDP, DERP relay, IPv4, and IPv6 paths. Increase the value only when the entire path supports it; lower it when diagnosing fragmentation or black-hole behavior.

7. Complete Configuration Examples

7.1 Basic tailnet access

[Proxy]
Personal Tailnet = tailscale, section-name=personal

[Tailscale personal]
auth-key = tskey-auth-example
hostname = surge-mac

7.2 MagicDNS with explicit test URL

[Proxy]
Office Tailnet = tailscale, section-name=office, test-url=http://health.office.example-tailnet.ts.net/, test-timeout=8

[Tailscale office]
auth-key = tskey-auth-example
hostname = surge-office
prefer-ipv6 = true

The test URL must resolve and route inside the tailnet.

7.3 Explicit exit node

[Proxy]
Tailnet Exit = tailscale, section-name=tailnet-exit, test-timeout=8

[Tailscale tailnet-exit]
auth-key = tskey-auth-example
hostname = surge-exit-client
exit-node = office-exit.example-tailnet.ts.net
idle-keepalive = 0

Only traffic assigned to Tailnet Exit by Surge uses the exit node.

7.4 Automatically select a single exit node

[Proxy]
Automatic Tailnet Exit = tailscale, section-name=auto-exit

[Tailscale auto-exit]
auth-key = tskey-auth-example
exit-node = auto

This configuration works only while exactly one usable exit-node candidate is visible. If two or more candidates are available, Surge intentionally selects none and asks for an explicit choice.

7.5 Use a custom control server and DNS resolver

[Proxy]
Private Tailnet = tailscale, section-name=private-tailnet

[Tailscale private-tailnet]
auth-key = tskey-auth-example
control-url = https://control.example.com
hostname = surge-private
dns-server = 100.64.0.53
mtu = 1280

7.6 Chain through another Surge policy

[Proxy]
Tailnet via Proxy = tailscale, section-name=chained-tailnet, underlying-proxy=Upstream

[Tailscale chained-tailnet]
auth-key = tskey-auth-example
hostname = surge-chained

Direct peer-to-peer UDP is disabled in this mode. Tailscale peer traffic uses DERP over the selected upstream policy.

7.7 Force DERP while dialing relays directly

[Proxy]
DERP-only Tailnet = tailscale, section-name=derp-only-tailnet

[Tailscale derp-only-tailnet]
auth-key = tskey-auth-example
hostname = surge-derp-only
derp-only = true

The control server and DERP servers are reached through DIRECT, but encrypted peer packets never use direct UDP paths.

8. Startup and Control-Plane Logic

The first connection, manual test, or other operation that needs the policy starts the session.

8.1 Identity state

Surge maintains persistent machine, node, and network-lock key material in its application-support storage. The state filename is derived from a SHA-256 hash of the auth key. The discovery key used for peer path discovery is ephemeral for a running session.

The persistent state allows a session to restart after idle teardown without unnecessarily replacing its cryptographic identity. Protect the application-support data as well as the profile auth key.

8.2 Registration sequence

The control sequence is:

1. Fetch the control server public key.
2. Establish a Noise-based control transport.
3. Open an HTTP/2 registration request.
4. Submit the machine key, node key, network-lock key, hostname, host information, endpoints, capabilities, and auth key.
5. Start the streaming map request.
6. Apply the returned local-node, peer, route, DNS, and DERP state.

The node is registered as ephemeral. Server-side retention and cleanup are still controlled by the control server.

Runtime control stages may appear as idle, fetching-key, connecting, registering, map-streaming, or closed. These stages are useful when diagnosing where startup is blocked.

8.3 Netmap streaming and reconnects

The control connection receives both full maps and incremental changes.

• A full map rebuilds the effective peer and route state.
• Existing peer tunnels are reused when a peer's node key has not changed.
• Incremental changes update or remove affected peers and rebuild routes as necessary.
• A control keepalive keeps the map stream active.
• If no map frame is observed for approximately 150 seconds, Surge reconnects the control stream.

Transient control errors use an increasing reconnect delay, beginning at roughly 100 milliseconds and capped at 30 seconds. A control reconnect preserves the data plane and existing peer tunnels whenever possible.

An authorization failure is treated as terminal for the current attempt: Surge tears down networking, reports the error, and fails new operations quickly. Applying corrected configuration or changing networks permits a fresh attempt. The network-change retry also accounts for false authorization symptoms caused by captive portals or TLS interception.

9. Peer Routing and WireGuard Logic

9.1 Route construction

Each authorized peer arrives with a set of allowed IP prefixes. Surge builds separate IPv4 and IPv6 route tables from those prefixes and uses the most specific matching route for each outbound packet.

Examples:

• A peer address route such as 100.x.y.z/32 reaches that individual node.
• A subnet route such as 10.20.0.0/16 reaches the authorized subnet router advertising it.
• A default route such as 0.0.0.0/0 or ::/0 represents an exit-node capability and is handled specially.

If no matching route exists, the packet cannot be delivered by this policy. Surge does not bypass the policy and send the packet directly.

9.2 WireGuard tunnels

Surge creates a WireGuard tunnel for each usable peer delivered by the control plane. Online peers may receive proactive handshakes; outbound traffic also initiates a handshake when needed.

A shared timer advances WireGuard timers, retransmissions, keepalives, and rehandshakes. If a peer tunnel has expired while active connections still depend on it, Surge requests a new handshake.

Packets are encrypted for the route-selected peer and handed to MagicSock, which chooses a direct endpoint or DERP relay path. Received WireGuard packets are decrypted and delivered to Surge's internal layer-3 stack.

10. Exit-Node Routing

An exit-node candidate is a peer that advertises an IPv4 or IPv6 default route. A candidate is usable only while the peer is present, online, and has an allocated tunnel.

10.1 Disabled mode

With exit-node = none, default routes from all peers are ignored. More specific tailnet and subnet routes remain usable.

If traffic that requires a default route is attempted while the tailnet does advertise one or more usable exit nodes, Surge drops the packet and reports a one-time warning that names the available exit nodes. This prevents a missing exit-node setting from being silently mistaken for a connectivity failure.

10.2 Automatic mode

With exit-node = auto:

• exactly one usable candidate: select it;
• no usable candidates: select none;
• two or more usable candidates: select none.

Ambiguity is intentional. Surge will not choose an arbitrary exit node because that could unexpectedly change egress location or trust boundaries. When default-route traffic is attempted with multiple candidates, Surge reports a warning containing the available node names.

10.3 Explicit mode

An explicit selector is compared against candidate peers using:

1. stable ID;
2. normalized full DNS name;
3. short DNS label; or
4. tailnet IPv4 or IPv6 address.

The match must be unique and the peer must be usable. A missing, offline, or ambiguous match produces no exit-node route and no automatic fallback.

10.4 Route installation

Only the selected exit node's default routes are installed. Default routes advertised by all other peers are ignored. This prevents overlapping exit nodes from competing in the route table.

Even with a selected exit node, Surge does not change the device's global default route. The exit node receives only the connections that Surge has already assigned to this Tailscale policy.

11. Direct Paths, DERP, and Network Discovery

MagicSock is responsible for selecting the transport path for encrypted peer packets.

11.1 Direct UDP sockets

When the effective underlying policy is DIRECT and derp-only is disabled, Surge opens physical UDP sockets and binds them to the primary physical interface. Binding avoids routing Tailscale's own transport packets back into the Surge virtual interface.

IPv6 UDP is opened only when the current network provides IPv6 connectivity. A missing IPv6 socket does not prevent IPv4 direct paths or DERP operation.

11.2 DERP relay

DERP provides a relay path when direct UDP connectivity is unavailable or not yet discovered.

• Surge initially chooses a provisional usable DERP region.
• Netcheck later refines the preferred region using measured latency.
• The home DERP connection is established during startup.
• Connections to other peer DERP regions are opened lazily when required.
• Home-region reconnects use increasing backoff; peer-region connections are retried when traffic needs them.

DERP relay is a valid working state, not necessarily an error. It normally has higher latency than a direct path.

When derp-only is enabled or a non-DIRECT underlying-proxy is selected, direct UDP sockets are not used, so DERP becomes the transport for peer packets.

11.3 Netcheck and endpoint reporting

After the DERP map and UDP sockets are ready, Surge runs network checks no more often than approximately once per minute. It probes STUN endpoints to discover public reflexive addresses, measures DERP reachability, collects local interface endpoints, and reports updated endpoints and the preferred DERP region to the control plane.

11.4 Peer path discovery

If no trusted direct path exists, Surge sends through DERP and starts peer endpoint discovery. Discovery probes candidate endpoints and exchanges endpoint information through DERP.

Key behaviors include:

• candidate discovery is rate-limited;
• a responsive direct endpoint is trusted for a short interval;
• recently active direct paths receive heartbeat probes;
• unanswered discovery pings expire;
• an alternative endpoint replaces the current best endpoint only when it is meaningfully faster, avoiding path flapping caused by tiny latency differences.

Runtime peer status indicates whether the current path is direct or relay, and may include the direct endpoint and measured latency.

12. DNS and MagicDNS

The control-plane DNS configuration contains resolver addresses, search domains, a MagicDNS flag, and optional extra records.

12.1 Resolver selection

Surge chooses resolvers in this order:

1. dns-server from the Tailscale section, when present;
2. resolver addresses delivered by the control plane.

The resulting list is private to this layer-3 policy. It does not globally replace the device's system DNS configuration.

12.2 MagicDNS records

When MagicDNS is enabled, Surge synthesizes local DNS records from:

• the local node DNS name and tailnet addresses;
• each visible peer's DNS name and tailnet addresses; and
• extra records supplied by the control plane.

Names are normalized to lowercase without a trailing dot. IPv4 and IPv6 records may both be present. prefer-ipv6 influences which family is preferred when both can be used.

12.3 Search domains

Search domains received from the control plane are applied to the policy DNS client. Fully qualified MagicDNS names are still the clearest choice in profiles and diagnostics because they do not depend on suffix expansion.

12.4 DNS routing dependency

DNS queries themselves travel through the Tailscale layer-3 policy. Consequently, an upstream resolver address needs a matching peer route. If name records appear in runtime status but external tailnet DNS queries time out, verify the resolver address and its advertised/authorized route.

13. Session Lifecycle and Idle Behavior

The session has four high-level runtime states:

• idle: The policy exists, but networking is not currently running.
• starting: Control, DERP, netmap, addressing, or data-plane setup is in progress.
• ready: The layer-3 session is ready to carry routed traffic.
• failed: A terminal startup or authorization error is present.

When the session is ready, Surge tracks active TCP connections and UDP mappings. Once both counts reach zero, the idle timer begins. At the configured idle-keepalive threshold, Surge releases networking resources.

A new connection restarts the session. The first operation after idle teardown may therefore include control, DERP, route, and WireGuard setup latency. Configure an always-on session only when this latency matters enough to justify continuous network and memory usage.

A network change invalidates the old sockets and causes control and transport state to be rebuilt. Peer data is refreshed from the new netmap and new network endpoints are reported.

14. Policy Testing and Latency Measurement

A Tailscale policy is tested in one of two modes. The mode is decided statically from the configuration, not from the live session state:

• A policy without a configured exit node (exit-node = none or omitted) and without an explicit test-url is treated as a peer-to-peer policy. It is not expected to provide Internet egress, so Surge measures tunnel reachability with the native Tailscale connectivity probe.
• A policy with a configured exit node, or with an explicit test-url, is expected to provide Internet egress, so Surge uses the standard URL test.

Because this decision is static, it does not depend on whether the session is currently running or whether an exit node happens to be online at the moment of testing. The same rule also governs which test controls are offered in the runtime status UI (see Runtime Status UI), so the available tests stay consistent regardless of session state.

14.1 Native Tailscale connectivity probe

This mode is used for a peer-to-peer policy: no explicit test-url and no configured exit node.

Surge prepares the session, then:

• probes a bounded set of eligible online peers using Tailscale discovery ping, preferring peers that already have a trusted direct path; or
• pings the home DERP connection when no eligible peer is available.

The result identifies whether the measured path is direct or relay where applicable. The reported RTT measures the connectivity probe itself and does not include session initialization time.

This is the correct test for a tailnet-only policy because it does not assume that the policy can reach a public Internet URL.

14.2 Standard URL test

This mode is used when:

• test-url is explicitly configured; or
• an exit node is configured (exit-node = auto or an explicit selector).

Surge sends an HTTP HEAD request through the policy. When the server permits connection reuse, a subsequent request can provide a latency value less dominated by initial connection setup. If the connection cannot be reused, the result includes more of the DNS, TCP, Tailscale, and server-response setup cost.

If an exit node is configured but not currently usable (offline, ambiguous, or unmatched), the URL test runs and fails rather than silently falling back to the peer probe. This surfaces the misconfiguration instead of hiding it.

14.3 Initialization allowance

Both test modes account for the potentially expensive first Tailscale startup. In addition to the effective test timeout, the overall operation receives 10 extra seconds for initialization and handshake work. The actual probe or URL request remains governed by the configured timeout, and the initialization allowance and the probe budget share a single deadline rather than being applied twice.

This distinction prevents a healthy first test from failing merely because it had to register, receive a netmap, connect to DERP, and establish an initial WireGuard handshake.

15. Runtime Status UI

Open the runtime details for a Tailscale policy to inspect its live state. Depending on platform and context, Surge presents common policy data in the main status view and Tailscale-specific data in detailed sections or submenus.

Common policy information includes:

• policy name and type;
• transferred bytes;
• current and peak speeds; and
• latest measured latency.

Tailscale-specific information may include:

• session state and control stage;
• registered hostname and control URL;
• local IPv4, IPv6, and MagicDNS name;
• effective underlying policy;
• effective transport mode when DERP-only operation is active;
• active TCP and UDP connection counts;
• idle keepalive value;
• configured exit-node selector, usable candidate count, and selected node;
• home DERP region and active relay regions;
• UDP socket ports and reported local/public endpoints;
• last netcheck age;
• DNS servers, search domains, and synthesized records; and
• peer names, addresses, online state, direct/relay path, endpoint latency, handshake state, and exit-node eligibility.

The test controls offered for a policy follow the same static classification as policy testing. A peer-to-peer policy (no configured exit node) exposes only the RTT test, because throughput, UDP, and NAT-type tests require Internet egress that such a policy does not provide. A policy with a configured exit node exposes the full set of tests. This choice is derived from configuration and does not change with session state.

An idle policy may have little peer or transport information until an operation starts the session. This is expected.

16. Troubleshooting

Registration fails immediately

Possible causes:

• missing, expired, revoked, or malformed auth key;
• a reusable key is required but the key is single-use and already consumed;
• the key requires interactive authorization;
• the control server rejected the hostname, tags, or node registration;
• the system clock, TLS interception, or captive portal prevents secure control access.

Check the runtime control stage and error. Replace the auth key when necessary. A network change permits a new attempt after a possible captive-portal failure.

The policy remains in starting

Inspect the control stage:

• fetching-key: control URL, DNS, TLS, or underlying connectivity issue;
• connecting: transport or proxy connection issue;
• registering: auth key or server authorization issue;
• map-streaming: the stream exists, but Surge may still be waiting for an address, DERP map, or usable local data plane.

Also verify that an underlying-proxy group resolves to a working final policy.

The session has no local address

The control plane assigns the local tailnet addresses. Confirm that the node is authorized and that the control server includes local addresses in the netmap.

A peer is visible but unreachable

Verify all of the following:

• the peer is online;
• ACLs allow the intended traffic;
• the destination address is included in the peer's delivered allowed routes;
• an advertised subnet route has been approved by the control plane;
• the packet does not exceed the configured MTU;
• the peer service is listening on the expected address and port.

A relay path is slower but should still work. If neither direct nor relay traffic works, inspect the peer handshake and DERP connection status.

Direct connectivity is never established

This is expected when derp-only = true or a non-DIRECT underlying-proxy is active, because direct UDP is deliberately disabled. Otherwise, restrictive NAT, firewalls, blocked UDP, or unavailable IPv6 may still force DERP relay.

exit-node = auto does not select a node

Automatic selection requires exactly one usable candidate. If more than one exit node is online, configure an explicit stable ID, DNS name, short name, or tailnet IP. If no candidate is usable, verify that the peer advertises and is authorized for default routes.

An explicit exit node is not selected

The selector must uniquely match an online usable candidate. Check spelling, DNS suffix, stable ID, tailnet address, peer online state, and control-plane exit-node approval. Surge does not fall back to another node.

MagicDNS names do not resolve

Check:

• whether MagicDNS is enabled in runtime DNS status;
• whether the peer DNS name appears in synthesized records;
• whether the control server supplied the expected search domain;
• whether a custom dns-server overrides the intended control resolver; and
• whether the resolver IP has a route through the Tailscale policy.

Try the peer's fully qualified DNS name and tailnet IP to separate DNS problems from routing problems.

A URL test fails while tailnet connections work

Without an exit node, an ordinary public URL is usually not routed through the policy. Remove test-url to use the native Tailscale probe, or configure a URL reachable through a peer/subnet route. With an exit node, confirm that it is selected and online.

Remember that a first URL test may use the configured timeout plus the additional 10-second initialization allowance.

First use after inactivity is slow

The default session is torn down after 600 idle seconds. Its next use must restart networking and may need a new WireGuard handshake. Increase idle-keepalive or set it to 0 if the additional background resource usage is acceptable.

Large transfers stall or particular packets disappear

The configured MTU may exceed the effective path MTU, or the application may generate packets larger than the layer-3 limit. Return to the default mtu = 1280 or reduce it while testing. Valid values are 576 through 1420.

17. Security and Operational Guidance

• Store auth keys only in sensitive profile storage and avoid sharing unredacted exports.
• Prefer HTTPS control URLs.
• Limit auth-key lifetime, reuse, tags, and ACL permissions.
• Remember that an exit node can observe and egress the traffic assigned to it; select it explicitly when multiple candidates exist.
• Treat a custom control server and DERP infrastructure as part of the trust boundary.
• Review control-plane ACLs and route approvals rather than relying only on Surge rules.
• Avoid using an overly broad Surge rule for an exit-node policy unless that routing scope is intentional.
• Prefer the default MTU unless path testing justifies a change.
• Use an always-on idle setting only when the latency benefit outweighs continuous background connections.

18. Configuration Reference

Minimal configuration:

[Proxy]
Tailnet = tailscale, section-name=tailnet

[Tailscale tailnet]
auth-key = tskey-auth-example

Configuration showing all Tailscale-section fields:

[Proxy]
Tailnet = tailscale, section-name=tailnet, test-timeout=8, ecn=true

[Tailscale tailnet]
auth-key = tskey-auth-example
control-url = https://controlplane.tailscale.com
hostname = surge-macos
derp-only = false
exit-node = none
idle-keepalive = 600
prefer-ipv6 = false
dns-server = 100.100.100.100
mtu = 1280

dns-server should normally be omitted so that the control-plane DNS configuration remains authoritative. The expanded example is a syntax reference, not a recommended template for every deployment.

Tailscale is a trademark of Tailscale Inc. This document describes Surge's compatible policy implementation and its behavior; it does not describe every feature of the standalone Tailscale client or control service.