Userspace networking (container+SOCKS) mode
Userspace Networking mode allows running Tailscale where you don’t have access to create a VPN tunnel device. This often happens in container environments.
Tailscale works on Linux systems using a device driver called /dev/net/tun, which allows us to instantiate the VPN tunnel as though it were any other network interface like Ethernet or Wi-Fi. This lets any Linux application — from a web browser to the
ping CLI command — send its traffic through the Tailscale interface.
However, not all Linux systems support /dev/net/tun. For example, some container-based app platforms such as Heroku or Google Cloud Run do not. For those environments, userspace networking mode offers a different way of running, where tailscaled functions as a SOCKS5 proxy which other processes in the container can connect through.
Step 1: Start tailscaled/tailscale in userspace networking mode
You can enable userspace networking from the Tailscale CLI by passing the
--tun=userspace-networking flag to tailscaled before calling
tailscaled --tun=userspace-networking --socks5-server=localhost:1055 & until tailscale up --authkey=<your auth key> do sleep 0.1 done
Userspace networking mode is primarily designed for serverless environments. We recommend using it with ephemeral nodes / auth keys (as shown above).
Step 2: Configure your application to use SOCKS5
Once Tailscale is authenticated, your application can connect using a SOCKS proxy. Many widely used networking packages support SOCKS5 already, generally by setting an
ALL_PROXY environment variable. For many applications, you’ll need a command like this:
Done! Your application should now be able to communicate with Tailscale devices on your network.
For instructions on how to use Tailscale on specific serverless platforms, see the articles below: