Warpgate

Warpgate is the lightweight sidecar agent that connects your workload to Altuur Secure Ingress. It implements the inverted ingress model: instead of opening inbound ports and configuring firewalls, Warpgate connects outward to Altuur’s global edge.

How it works

1. Warpgate starts alongside your workload
2. It initiates an outbound TLS 1.3 connection to Altuur’s global edge
3. It authenticates using a service account API key
4. Secure Ingress forwards end-user traffic through this established tunnel
5. Warpgate passes the traffic to your workload over a private network path: localhost inside a Kubernetes pod, the service name on a Compose network, or the host it runs next to

Your workload does not need to accept inbound connections from the internet: no open inbound ports, no inbound firewall rules, and no public IP address are required. Adding Warpgate does not remove a public listener that already exists, so close or firewall any direct path to the workload (see Close the direct path).

Deployment options

Create the service account first: Warpgate authenticates with a service account API key that you generate in the Console under your project’s Service Accounts. The examples below use YOUR_API_KEY as a placeholder for that key.

Docker Compose

The recommended way to run Warpgate with a containerized application. Both run as services on the same Compose project, which gives them a private network: Warpgate reaches the application by service name, and the application has no ports: entry, so it is reachable only from inside that network.

services:
  app:
    image: your-app:latest
    # No ports: the app is reachable only on the private Compose network

  warpgate:
    image: mezusphere/warpgate
    command: ["--api-key", "YOUR_API_KEY", "--upstream-url", "http://app:8080"]
    depends_on:
      - app

Docker with an application on the host

If the application runs directly on the host, map the host into the Warpgate container and point the upstream at it. Inside a container, localhost refers to the container itself, not the host.

docker run --add-host=host.docker.internal:host-gateway mezusphere/warpgate \
  --api-key YOUR_API_KEY \
  --upstream-url http://host.docker.internal:8080

This variant assumes the application listens on the host and accepts connections from the Docker bridge network (for example by binding to 0.0.0.0:8080), and that the port is not exposed publicly: your host firewall or cloud security group must keep it closed to the internet so that only Warpgate can reach it.

Echo mode

Verify connectivity before wiring an upstream. With --echo, Warpgate answers every request through your endpoint with a JSON reflection of the request it received: method, path, headers, and identity.

docker run mezusphere/warpgate --api-key YOUR_API_KEY --echo

When the echo response comes back through your endpoint, replace --echo with --upstream-url and point it at your service.

The mezusphere/warpgate image is multi-arch (linux/amd64, linux/arm64) and runs anywhere Docker or Kubernetes runs, including arm64 edge devices.

Kubernetes

Deploy Warpgate as a sidecar container in your pod:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-service
spec:
  template:
    spec:
      containers:
        - name: app
          image: your-app:latest
          ports:
            - containerPort: 8080
        - name: warpgate
          image: mezusphere/warpgate
          args:
            - "--api-key"
            - "YOUR_API_KEY"
            - "--upstream-url"
            - "http://localhost:8080"

Containers in a pod share a network namespace, so localhost is correct here. containerPort documents the port; it does not publish it outside the cluster. Do not add a Service or Ingress for the application; Warpgate is its only route in.

Works with any Kubernetes distribution: EKS, GKE, AKS, k3s, or self-managed clusters.

Close the direct path

Adding Warpgate does not remove an existing public IP address, listener, or firewall rule. If the workload was reachable from the internet before, remove the published port, the DNS record, or the security-group rule that exposed it, or restrict it to trusted addresses, so that the only route to the workload is through the Altuur Edge. The isolation properties described under Security depend on this.

Configuration

Command-line flags

Environment variables

Every flag can also be set via an environment variable: the flag name in uppercase with underscores, no prefix.

Connectivity

Outbound connection

Warpgate establishes a persistent outbound connection to Altuur’s global edge using TLS 1.3 with mutual authentication (mTLS). The connection is:

• Encrypted: TLS 1.3, no downgrade
• Authenticated: mutual TLS with service account credentials
• Persistent: maintained for the lifetime of the Warpgate process
• Reconnecting: automatic reconnection with backoff on network interruption

Network requirements

Warpgate requires only outbound HTTPS connectivity. No inbound ports, no inbound firewall rules, no VPN configuration needed.

Cloud-agnostic

Warpgate works identically regardless of where your workload runs:

• AWS (EC2, ECS, EKS, Lambda)
• Google Cloud (GCE, GKE, Cloud Run)
• Azure (VMs, AKS, Container Instances)
• On-premises data centers
• Local development machines
• Edge devices (Raspberry Pi, IoT)

The deployment pattern is always the same: run Warpgate alongside your workload, provide a token, point it at your upstream.

Resource usage

Warpgate is designed to be lightweight:

• A single static binary inside a minimal container image (mezusphere/warpgate)
• Minimal memory footprint
• Negligible CPU overhead
• No disk I/O beyond logging

It is not a proxy, not a service mesh control plane, and not an agent that phones home with telemetry. Its only connections are the outbound tunnels and control-plane session described above.

For your own monitoring, Warpgate can expose a local Prometheus /metrics endpoint with standard reverse-proxy metrics: request rate, latency, sizes, upstream health, and tunnel reconnects. It is off by default (enable with --metrics-addr), and nothing is reported back to Secure Ingress.