NAT Traversal

Reaching your Mac and home network while away, browsing with your home broadband IP, debugging a development box at the office — these used to mean a public IP, router port forwarding, or self-hosted tunneling services. Stash builds NAT traversal in as an out-of-the-box capability, with two solutions:

• StashLink: Stash’s own device interconnection protocol. Sign in to the same iCloud account and the network is up — zero configuration, zero servers, end-to-end encrypted, ideal for quickly connecting your own Apple devices.
• Built-in Tailscale: complete Tailscale node capability. Ideal if you already have a tailnet, need cross-platform devices, or want more sophisticated networking.

Both can run at the same time, and both work seamlessly with Stash’s routing rules.

StashLink

StashLink turns devices signed in to the same iCloud account into a private encrypted network of your own:

• Zero-configuration networking: no account to register, no server to host, no public IP or port forwarding — devices discover each other automatically.
• End-to-end encryption: devices connect to each other directly over encrypted connections and authenticate with device certificates; only your devices can join the network.
• Smart path selection: devices on the same LAN connect locally; across networks, NAT hole punching establishes a peer-to-peer connection; on restrictive networks, traffic automatically relays through a proxy node you already have.
• Full forwarding capability: both TCP and UDP are forwarded, and StashLink nodes participate in routing rules and proxy groups like any other proxy.

How It Works

Devices discover each other by exchanging a small amount of addressing information through iCloud, then connect using the following priorities:

Whichever path is used, data stays end-to-end encrypted between your two devices: even when relayed, the relay node only forwards ciphertext and sees nothing of what you transfer. iCloud is used solely to sync addressing information, and Stash does not operate any traffic relay servers.

Stash running on a Mac automatically becomes the reachable end. Keep one Mac at home running Stash, and your iPhone, iPad, and other Macs can dial home anytime.

Using a Device as a Proxy

Declare a type: stashlink proxy in your configuration to turn another device into your egress. The device ID is shown on the peer device under “Tools” → “System Info”.

proxies:
  - name: HOME-MAC
    type: stashlink
    device-id: 1a2b3c4d5e6f7a8b
 
rules:
  # Home LAN goes through the Mac at home
  - IP-CIDR,192.168.1.0/24,HOME-MAC,no-resolve
  # Selected sites use the home IP
  - DOMAIN-SUFFIX,example.com,HOME-MAC

Typical scenarios:

• Reach your home network: NAS, router admin pages, smart home devices — all reachable anytime.
• Browse with your home IP: send selected apps or sites through your home broadband for a stable home network identity.
• Remote development: reach services on a dev machine at home or in the office while away.

StashLink Auto

NAT hole punching does not succeed on every network, and relaying needs a carrier. StashLink Auto automates all of it, with nothing to configure:

• Automatic selection: picks a relay carrier from the proxies and subscription nodes in your configuration, preferring the lowest latency.
• Verified before publishing: each candidate passes a real connectivity self-test (a complete encrypted handshake) before use; only verified-reachable addresses are published to your other devices.
• Continuous guarding: repeated failures switch to the next candidate automatically; the selection is refreshed after network changes and subscription updates.

You can also pin the relay carrier manually, in which case Stash uses only the specified node:

stashlink:
  underlying-proxy:
    type: ss
    server: relay.example.com
    port: 8388
    cipher: aes-128-gcm
    password: password

Device Domains

Every device automatically gets a .stash domain. <device-name>.stash:<port> reaches the corresponding port on that device itself:

# Reach a service running on the Mac at home
curl http://steve-s-mac-mini.stash:9090
 
# SSH to the Mac at home
ssh steve@steve-s-mac-mini.stash

• Domains come from device names and sync automatically through iCloud: a device named “Steve’s Mac mini” automatically gets steve-s-mac-mini.stash. Special characters are converted automatically, and devices with identical names get a device ID suffix, so a domain never points at the wrong device.
• A service listening only on the peer’s 127.0.0.1, never exposed to the LAN, is still reachable through its device domain.
• Both TCP and UDP are supported, and any app going through Stash can use device domains directly.

Device domains are on by default and can be turned off in the configuration:

stashlink:
  device-dns: false

Built-in Tailscale

Stash embeds a complete Tailscale node in its proxy engine: declare a type: tailscale proxy and Stash becomes a device in your tailnet.

• Join an existing tailnet: interconnect with devices on any platform — Linux, Windows, NAS, Raspberry Pi — share devices with others, and manage access with ACLs.
• Exit Node: use any exit node in your tailnet as a Stash proxy egress.
• Self-hosted control server: control-url supports Headscale and other self-hosted control planes.
• Direct connections and DERP relays: automatic NAT hole punching for peer-to-peer connections, with Tailscale’s global DERP relay network as the fallback.
• Coexists with routing rules: iOS runs only one VPN tunnel at a time; Stash lets Tailscale networking and proxy routing work together inside the same tunnel.

Onboarding completes automatically with an auth-key, or interactively in the app:

proxies:
  - name: ts-main
    type: tailscale
    auth-key: tskey-auth-xxxxxxxxxxxxxxxx

Automatic Tailnet Routing and MagicDNS

Once a Tailscale node is running, Stash automatically routes the tailnet’s MagicDNS suffix and peer addresses to it: MagicDNS names like hostname.tailnet-name.ts.net resolve and connect directly, with no rules to write and no DNS changes to make; everything else keeps matching your routing rules as usual.

For full parameters and authentication flows, see the Tailscale proxy protocol.

Which One to Choose

In short: to reach your own devices, pick StashLink — it just works; for cross-platform devices, multiple users, or fine-grained network management, pick built-in Tailscale. They do not conflict and can run side by side.