Userspace Networking | Twingate

Userspace Networking

Run Twingate without root privileges using HTTP Proxy Mode

Summary

Twingate’s Linux client supports a userspace (non-root) networking mode that enables secure access to private resources using standard HTTP and HTTPS traffic.

This mode is designed for environments where elevated privileges are unavailable or undesirable, such as containers, CI/CD pipelines, cloud-native workloads, and managed workstations.

Instead of creating a kernel-level tunnel interface (TUN), the client runs as an HTTP/HTTPS proxy. Applications explicitly send traffic through the proxy, allowing Twingate to enforce identity-based access without requiring root access.

Common use cases include:

Reminder

Peer-to-peer connections help you to provide a better experience for your users and to stay within the Fair Use Policy for bandwidth consumption. Learn how to support peer-to-peer connections.

Available Network Modes

Mode Description Root Required Default
TUN Mode Full-network tunneling for all protocols ✅ Yes ✅ Enabled
HTTP Proxy Mode HTTP/HTTPS traffic only, ideal for userspace environments ❌ No Disabled
TUN + HTTP Proxy Mode Hybrid mode supporting both methods ✅ Yes Disabled

Why It Matters

1. Run Without Root

Many developer and automation environments restrict root access. HTTP Proxy Mode provides secure connectivity under these conditions without compromising access to protected resources.

2. Simpler Integration for Containers

Run Twingate as part of Docker or Kubernetes workflows without modifying host networking or running privileged containers.

3. Safer Defaults for Automation

Adopt a least-privilege model while maintaining secure access for non-interactive or headless jobs. For more least-privilege policy information take a look at our auto lock and just in time access features.

How It Works

In HTTP Proxy Mode, the Twingate Client runs a local HTTP/HTTPS proxy (for example on port 9999).

Applications or scripts connect to this proxy using standard HTTP CONNECT semantics.

Twingate then evaluates the request (whether to capture or not), and forwards traffic over the secure tunnel.

This enables userspace connectivity without kernel-level network changes.

Important: Traffic is not intercepted automatically. Applications must explicitly use the proxy.

Prerequisites

Before using HTTP Proxy Mode, ensure one of the following authentication methods is configured:

Note

Service accounts are available for Business and Enterprise plan customers and provide the easiest way to integrate Twingate into automated workflows. Learn more about Service Accounts.

Configuration Examples

HTTP Proxy Only (No Root Required)

twingated --http-proxy 0.0.0.0:9999 --tun off

This starts the client in userspace mode and listens for proxy connections on port 9999.

Hybrid Mode (Root Required)

sudo twingated --http-proxy 0.0.0.0:9999 --tun on

This enables both full tunneling and proxy access.

Using Environment Variables

Set environment variables for consistent configuration across deployments:

export TWINGATE_HTTP_PROXY=0.0.0.0:9999
export TWINGATE_TUN=off
twingated

Using a Config File

Create a persistent configuration file for system-wide settings:

echo '{"http-proxy": "0.0.0.0:9999", "tun": "off"}' | sudo tee /etc/twingate/network-config.json
twingated

Interactive CLI Helpers

# Show current networking config
twingate config networking

# Enable HTTP proxy only (explicitly disable TUN)
twingate config networking http-proxy=0.0.0.0:9999 tun=off

# Enable HTTP proxy and leave TUN on (implicit)
twingate config networking http-proxy=0.0.0.0:9999

# Enable HTTP proxy and TUN explicitly
twingate config networking http-proxy=0.0.0.0:9999 tun=on

Container Deployments

Kubernetes

Example configuration for deploying the Twingate Client in a Kubernetes cluster:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: twingate-headless
spec:
  template:
    spec:
      containers:
        - name: twingate-headless
          imagePullPolicy: IfNotPresent
          image: twingate/client:latest
          command: ["/usr/sbin/twingated", "--http-proxy", "0.0.0.0:9999", "--tun", "off"]
          ports:
            - containerPort: 9999
              protocol: TCP
          volumeMounts:
            - mountPath: "/etc/twingate/service_key.json"
              name: twingate-service-key
              subPath: twingate-service-key

Docker Compose

Proxy Used by Other Containers (Recommended Default)

If only containers in the same Docker Compose project (or same Docker network) need access, do not expose the proxy port:

services:
  twingate-client:
    image: twingate/client:latest
    command: --http-proxy 0.0.0.0:9999 --tun off
    volumes:
      - ./service_key.json:/etc/twingate/service_key.json:ro

# Example container using twingate-client proxy
  uptime-kuma:
    image: louislam/uptime-kuma:1
    depends_on:
      - twingate-client
    ports:
      - 3001:3001
    volumes:
      - uptime-kuma-data:/app/data

volumes:
  uptime-kuma-data:

Containers can reach the proxy via:

http://twingate-client:9999

For the Uptime Kuma example above:

Only monitors explicitly configured with this proxy will be tunneled through Twingate.

Proxy Accessed from Host or LAN Devices

If the proxy should be accessible from the host or other devices on the local network, the port must be published:

services:
  twingate-client:
    image: twingate/client:latest
    command: --http-proxy 0.0.0.0:9999 --tun off
    ports:
      - "9999:9999"
    volumes:
      - ./service_key.json:/etc/twingate/service_key.json:ro

You can then configure clients to use:

http://<host-ip>:9999

Testing the Proxy (from Host Device)

curl -v --proxy http://127.0.0.1:9999 https://ipinfo.io/what-is-my-ip

Where *ipinfo.io is a Twingate Resource address, a successful response returning a cloud IP confirms traffic is routed through the Twingate Client.

Troubleshooting

If access fails or traffic does not appear to be routed through Twingate:

For container deployments:

For additional help, see the Twingate Troubleshooting Guide.