Userspace Networking

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:

• CI/CD pipelines or build systems
• Docker or Kubernetes workloads
• Developer workstations without sudo access
• Cloud-native or multi-tenant systems

Available Network Modes

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:

• Interactive setup: Configure the client via twingate setup for desktop/interactive use
• Headless mode: Place a service key at /etc/twingate/service_key.json for automated deployments

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:

• Open the Uptime Kuma UI at http://localhost:3001

• Go to Settings → Proxies

• Add a new proxy:

• Type: HTTP
• Host: twingate-client
• Port: 9999

• Assign this proxy to any monitor that should access Twingate-protected resources

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

⚠️ Publishing the proxy exposes it to your LAN network. Use firewall rules or interface binding as appropriate.

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:

• Confirm the Twingate Client is running and authenticated
• Verify the service key exists at /etc/twingate/service_key.json if using headless mode
• Ensure the application is explicitly using the HTTP proxy
• Check the Resource address or alias matches the requested domain or IP address
• Review Recent Activity for the Resource in the Admin Console

For container deployments:

• Ensure containers share the same Docker network (if the proxy port is not published)
• Verify the correct proxy address is used (twingate-client:9999 vs 127.0.0.1:9999)
• Check that NO_PROXY settings are not bypassing the proxy unintentionally

For additional help, see the Twingate Troubleshooting Guide.

Related Resources

• Twingate Headless & AWS ECS