Tunneling Service

The Tunneling Service enables nodes to communicate across different networks, even when behind NAT/firewalls. This is essential for Account-Based and Proximity Discovery, where nodes on different networks need to reach each other.

Prerequisites

Tunneling requires a developer account and account association:

1. Developer Console: Create a project and get your Client ID and Developer ID Token
2. Account Association: Associate your mimOE node with your developer account to obtain an access token

The access token from account association is what you store via PUT /token in the API usage below.

Overview

Attribute	Value
Purpose	NAT traversal for cross-network communication
Cloud dependency	Requires mSS (mimik Signaling Service)
Connection	Outbound HTTPS to tunnel service
Capabilities	HTTP RESTful APIs only
Protocol	Request/response relay

Why Tunneling is Needed

Most nodes are behind NAT/firewalls:

• Nodes have private IP addresses (192.168.x.x, 10.x.x.x)
• Routers block inbound connections by default
• External nodes cannot directly reach internal nodes
• Opening firewall ports is often not possible on mobile or corporate networks

The Tunneling Service solves this by reversing the connection direction: nodes maintain outbound connections to the tunnel service, which relays incoming requests through those connections.

Tunnel Architecture

mimOE provides two types of tunnels for optimized cross-network communication.

SEP (Signaling Endpoint)

SEP is established on a proxy node selected by the supernode (typically the supernode itself). Instead of each node in the local mesh establishing its own tunnel, a single SEP enables all local nodes to be reachable from outside the network.

Characteristics:

• One tunnel serves the entire local mesh
• Reduces overhead by eliminating per-node tunnel establishment
• Proxy node routes requests to the appropriate local node
• Optimization unique to mimOE architecture

BEP (Bearer Endpoint)

When a particular node requires high-volume communication, a mim can request a BEP (a direct tunnel that bypasses the SEP entirely).

Characteristics:

• Established on-demand for heavy communication scenarios
• Direct connection between specific nodes
• Avoids routing through the proxy node
• Better performance for sustained traffic

Typical Request Flow

1. A requesting mim discovers another mim on a different network via discovery service
2. The requesting mim uses SEP to reach the target mim through the proxy node
3. The requesting mim authenticates with the target mim
4. For heavy traffic, the requesting mim asks the target mim to establish a BEP
5. Subsequent communication uses BEP directly

API Usage

Tunneling uses the Insight API to get the SEP routing information, then includes routing headers when calling a remote node.

Step 1: Store a JWT

Tunneling requires an account-scoped token:

curl -X PUT "http://localhost:8083/mimik-mesh/insight/v1/token" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "token": "eyJhbGciOiJSUzI1NiIs...",
    "expiresAt": 1729677600
  }'

Step 2: Get SEP Info

Retrieve the service endpoint for cross-network routing:

curl -X GET "http://localhost:8083/mimik-mesh/insight/v1/info?types=sep" \
  -H "Authorization: Bearer $API_KEY"

Response (200 OK)

{
  "data": {
    "sep": {
      "nodeId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "url": "https://sep.mimik.com",
      "headers": {
        "x-mimik-port": "8083",
        "x-mimik-routing": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      },
      "status": "available"
    }
  }
}

Step 3: Call a Remote Node

Use the SEP url as the base and include the routing headers to reach a mim on the remote node:

curl -X GET "https://sep.mimik.com/my-agent/v1/data" \
  -H "Authorization: Bearer $API_KEY" \
  -H "x-mimik-port: 8083" \
  -H "x-mimik-routing: a1b2c3d4-e5f6-7890-abcd-ef1234567890"

This routes the request through the mimik cloud relay to the target node, where it is forwarded to the local mim at /my-agent/v1/data.

See the Insight API reference for full details.

Current Capabilities

The Tunneling Service currently supports HTTP RESTful API requests only:

• All standard HTTP methods (GET, POST, PUT, DELETE, PATCH)
• Request and response headers preserved
• JSON, form data, and binary payloads
• Configurable request timeouts

Limitations

The following are not currently supported for tunneled connections:

• WebSocket connections
• Server-Sent Events (SSE)
• Streaming responses
• Long-lived connections beyond request timeout

For applications requiring WebSocket or streaming, nodes must be on the same network using Link Local Discovery, which supports full HTTP, WebSocket, and SSE capabilities.

When Tunneling is Used

The mDS (mimik Discovery Service) determines whether tunneling is required based on network topology. When a local mesh has no reachable public IP, mDS assigns a SEP as a proxy node, selected by the supernode, to facilitate communication.

Scenario	Connection	How it works
Same network (Link Local)	Direct	Nodes reach each other directly via local network
Different networks, no public IP	Tunneled	mDS detects NAT and assigns SEP proxy
Node has public IP	Direct	mDS determines direct connection is possible

Security

• Transport encryption: All tunnel connections use TLS (HTTPS)
• Node authentication: Only registered nodes can establish tunnels
• Request authentication: Requests include signed tokens
• Account isolation: Cross-account tunneling only for public services

Related

• Link Local Discovery
• Account-Based Discovery
• Proximity Discovery