Docs / Admin

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.

Userspace networking mode is a new feature in Tailscale v1.8 or greater. Update your clients to use it.

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 tailscale up

tailscaled --tun=userspace-networking --socks5-server=localhost:1055 &
until tailscale up --authkey=<your auth key>
    sleep 0.1

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:

ALL_PROXY=socks5://localhost:1055/ ./my-app

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:

We’d love to hear about the cool things you build. Mention @tailscale on Twitter or email us at [email protected].

Last updated