{"slug":"userspace-networking-mode-for-containers","title":"Userspace networking mode (for containers)","tags":["tailscale","networking"],"agent_summary":"Last validated: Nov 12, 2025","trigger_phrases":[],"runnable":false,"markdown":"\r\n# Userspace networking mode (for containers)\r\n\r\nLast validated: Nov 12, 2025\r\n\r\nUserspace networking mode lets you run Tailscale where you don't have access to create a VPN tunnel device. This often happens in container environments.\r\n\r\nTailscale works on Linux systems using a device driver called `/dev/net/tun`, which lets you start 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.\r\n\r\nHowever, not all Linux systems support `/dev/net/tun`. For example, some container-based app platforms like [Heroku](https://tailscale.com/docs/install/cloud/heroku) and [Google Cloud Run](https://tailscale.com/docs/install/cloud/cloudrun) do not. For those environments, userspace networking mode offers a different way of running, where `tailscaled` functions as a SOCKS5 or HTTP proxy which other processes in the container can connect through.\r\n\r\n![A diagram of userspace networking in Tailscale.](https://tailscale.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fuserspace-networking.024f13f4.png&w=3840&q=75)\r\n\r\nUserspace networking mode with SOCKS5 is available in Tailscale v1.8 or later. The HTTP proxy is available in Tailscale v1.16 or later. [Update Tailscale](https://tailscale.com/docs/features/client/update) to use these features.\r\n\r\n## [SOCKS5 vs. HTTP](https://tailscale.com/docs/concepts/userspace-networking\\#socks5-vs-http)\r\n\r\nThe functionality and purpose of the SOCKS5 and HTTP proxies varies. The SOCKS5 proxy is a more general and flexible proxy that can work with any traffic. The HTTP proxy is only for that protocol, so it only proxies HTTP and HTTPS traffic, for example, to web pages.\r\n\r\n## [Start Tailscale in userspace networking mode](https://tailscale.com/docs/concepts/userspace-networking\\#start-tailscale-in-userspace-networking-mode)\r\n\r\nYou can enable userspace networking from the [Tailscale CLI](https://tailscale.com/docs/reference/tailscale-cli) by passing the `--tun=userspace-networking` flag to `tailscaled` before running `tailscale up`. You can also use a SOCKS5 proxy and an HTTP proxy on the same port (as shown in the following code block),\r\n\r\n```shell\r\ntailscaled --tun=userspace-networking --socks5-server=localhost:1055 --outbound-http-proxy-listen=localhost:1055 &\r\ntailscale up --auth-key=\r\n```\r\n\r\nUserspace networking mode is primarily for [serverless environments](https://tailscale.com/docs/integration-serverless-apps). We recommend using it with [ephemeral nodes and auth keys](https://tailscale.com/docs/features/ephemeral-nodes) (as shown above).\r\n\r\nYou can enable userspace networking mode on Ubuntu, RHEL, or any derivative by adding the flag `--tun=userspace-networking` to the `FLAGS` variable in `/etc/default/tailscaled`:\r\n\r\n```markup\r\nFLAGS=\"--tun=userspace-networking\"\r\n```\r\n\r\nThe Tailscale Docker image supports a [`TS_USERSPACE`](https://tailscale.com/docs/features/containers/docker#ts_userspace) parameter that is equivalent to `tailscaled --tun=userspace-networking`.\r\n\r\n## [Configure your application to use SOCKS5 or HTTP](https://tailscale.com/docs/concepts/userspace-networking\\#configure-your-application-to-use-socks5-or-http)\r\n\r\nAfter Tailscale is authenticated, your application can connect using a SOCKS5 or HTTP proxy or both. Many widely used networking packages support these proxies already, generally by setting the `ALL_PROXY` and `HTTP_PROXY`environment variables. For many applications, you'll need a command like this:\r\n\r\n```shell\r\nALL_PROXY=socks5://localhost:1055/ HTTP_PROXY=http://localhost:1055/ http_proxy=http://localhost:1055/ ./my-app\r\n```\r\n\r\nSome libraries use `http_proxy` instead of `HTTP_PROXY`. You might need to experiment to find the right setting for your application. For instructions on how to use Tailscale on specific serverless platforms, refer to the topics below:\r\n\r\n- [Tailscale on Heroku](https://tailscale.com/docs/install/cloud/heroku)\r\n- [Tailscale on Google Cloud Run](https://tailscale.com/docs/install/cloud/cloudrun)\r\n- [Tailscale on GitHub Actions](https://tailscale.com/blog/2021-05-github-actions-and-tailscale)\r\n\r\n![Project Logo](https://cdn.brandfetch.io/tailscale.com/fallback/lettermark/theme/dark/h/256/w/256/icon?c=1bfwsmEH20zzEfSNTed)\r\n\r\nAsk AI\r\n\r\nreCAPTCHA\r\n\r\nRecaptcha requires verification.\r\n\r\nprotected by **reCAPTCHA**\r\n","html":"

Userspace networking mode (for containers)

\n

Last validated: Nov 12, 2025

\n

Userspace networking mode lets you run Tailscale where you don't have access to create a VPN tunnel device. This often happens in container environments.

\n

Tailscale works on Linux systems using a device driver called /dev/net/tun, which lets you start 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.

\n

However, not all Linux systems support /dev/net/tun. For example, some container-based app platforms like Heroku and Google Cloud Run do not. For those environments, userspace networking mode offers a different way of running, where tailscaled functions as a SOCKS5 or HTTP proxy which other processes in the container can connect through.

\n

\"A

\n

Userspace networking mode with SOCKS5 is available in Tailscale v1.8 or later. The HTTP proxy is available in Tailscale v1.16 or later. Update Tailscale to use these features.

\n

SOCKS5 vs. HTTP

\n

The functionality and purpose of the SOCKS5 and HTTP proxies varies. The SOCKS5 proxy is a more general and flexible proxy that can work with any traffic. The HTTP proxy is only for that protocol, so it only proxies HTTP and HTTPS traffic, for example, to web pages.

\n

Start Tailscale in userspace networking mode

\n

You can enable userspace networking from the Tailscale CLI by passing the --tun=userspace-networking flag to tailscaled before running tailscale up. You can also use a SOCKS5 proxy and an HTTP proxy on the same port (as shown in the following code block),

\n
tailscaled --tun=userspace-networking --socks5-server=localhost:1055 --outbound-http-proxy-listen=localhost:1055 &\r\ntailscale up --auth-key=<your-auth-key>\n
\n

Userspace networking mode is primarily for serverless environments. We recommend using it with ephemeral nodes and auth keys (as shown above).

\n

You can enable userspace networking mode on Ubuntu, RHEL, or any derivative by adding the flag --tun=userspace-networking to the FLAGS variable in /etc/default/tailscaled:

\n
FLAGS=\"--tun=userspace-networking\"\n
\n

The Tailscale Docker image supports a TS_USERSPACE parameter that is equivalent to tailscaled --tun=userspace-networking.

\n

Configure your application to use SOCKS5 or HTTP

\n

After Tailscale is authenticated, your application can connect using a SOCKS5 or HTTP proxy or both. Many widely used networking packages support these proxies already, generally by setting the ALL_PROXY and HTTP_PROXYenvironment variables. For many applications, you'll need a command like this:

\n
ALL_PROXY=socks5://localhost:1055/ HTTP_PROXY=http://localhost:1055/ http_proxy=http://localhost:1055/ ./my-app\n
\n

Some libraries use http_proxy instead of HTTP_PROXY. You might need to experiment to find the right setting for your application. For instructions on how to use Tailscale on specific serverless platforms, refer to the topics below:

\n\n

\"Project

\n

Ask AI

\n

reCAPTCHA

\n

Recaptcha requires verification.

\n

protected by reCAPTCHA

\n"}