# 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:

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

### Reminder

[Peer-to-peer connections](/content/docs/peer-to-peer-communication-in-twingate/index.html) help you to provide a better experience for your users and to stay within the [Fair Use Policy](/content/terms/sa/index.html) for bandwidth consumption. Learn how to [support peer-to-peer connections](/content/docs/troubleshooting-p2p/index.html).

### 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](/content/docs/%22/usage-based-auto-lock%22/index.html) and [just in time access](/content/docs/%22/jit-access-requests%22/index.html) 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](https://datatracker.ietf.org/doc/html/rfc7231#section-4.3.6) 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

### 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](/content/service-accounts-guide/index.html).

## Configuration Examples

### HTTP Proxy Only (No Root Required)

```bash
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)

```bash
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:

```bash
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:

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

### Interactive CLI Helpers

```bash
# 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:

```yaml
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**:

```yaml
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:

```text
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:

```yaml
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:

```text
http://<host-ip>:9999
```

### Testing the Proxy (from Host Device)

```bash
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](/content/docs/troubleshooting/index.html).