Tunnel Configuration Reference

Traffic bridging between the WireGuard tunnel and the HTTP server.

When Tailscale direct mode is active (TailscaleConfig.direct = true), the embedded WireGuard data plane terminates encrypted UDP traffic and bridges decrypted TCP streams to the HTTP server via Unix socketpairs. The HTTP server sees bridged connections as ordinary TCP connections — no application-level changes are needed.

When direct mode is not active, this configuration block is ignored.

Inbound bridging

Inbound TCP connections from the WireGuard tunnel's userspace netstack are bridged to the HTTP server. Remote Tailscale nodes connect to listenPort on this node's Tailscale IP.

Outbound bridging

When the HTTP handler makes an outbound connection to an address within tailnetRanges (e.g., reverse-proxying to another node), the connection is routed through the tunnel's netstack instead of the kernel network stack.

Example

pkl

tunnel {
  bridgeInbound = true
  bridgeOutbound = true
  listenPort = 443
}

> This page is auto-generated from the PKL schema. See the guide for usage examples.

`TunnelConfig`

Open class — can be extended.

WireGuard tunnel bridging configuration.

Requires TailscaleConfig.direct = true in the parent network configuration. When Tailscale is not in direct mode, all fields in this block are ignored.

Field	Type	Default	Description
`bridgeInbound`	Boolean	`true`	Bridge inbound TCP connections from the WireGuard tunnel to the
`bridgeOutbound`	Boolean	`true`	Route outbound connections through the WireGuard tunnel when the
`listenPort`	UInt16	`443`	TCP port the userspace netstack listens on for inbound connections.
`tailnetRanges`	Listing	`new {`	CIDR ranges whose outbound connections are routed through the

`bridgeInbound`

Bridge inbound TCP connections from the WireGuard tunnel to the HTTP server.

When true, the tunnel's userspace netstack listens on listenPort and forwards accepted connections to the HTTP server as pipe file descriptors. Set to false to use this network for outbound-only connectivity.

Default: true

`bridgeOutbound`

Route outbound connections through the WireGuard tunnel when the destination matches tailnetRanges.

When true, outbound connections to Tailscale IPs are routed through the embedded WireGuard data plane. When false, all outbound connections use the kernel network stack regardless of destination.

Default: true

`listenPort`

TCP port the userspace netstack listens on for inbound connections.

Remote Tailscale nodes connect to this port on the node's Tailscale IP to reach the HTTP server. Use 443 for HTTPS or 80 for plaintext HTTP. Only relevant when bridgeInbound = true.

Default: 443

`tailnetRanges`

CIDR ranges whose outbound connections are routed through the tunnel instead of the kernel network stack.

The defaults cover Tailscale's CGNAT range (100.64.0.0/10) and its ULA IPv6 range (fd7a:115c:a1e0::/48). Only relevant when bridgeOutbound = true. Add entries here if your tailnet uses additional subnet routes that should traverse the tunnel.

pkl

tailnetRanges {
  "100.64.0.0/10"
  "fd7a:115c:a1e0::/48"
  "10.10.0.0/16"  // extra subnet route
}

---