Cube HTTP

A lightweight HTTP tunneling solution built with Node.js and WebSockets.

Cube HTTP allows you to securely expose a local HTTP service to the internet through a single persistent WebSocket connection, similar to tools like ngrok but with a minimal self-hosted architecture.

Features

• HTTP tunneling over WebSocket
• Self-hosted
• Token-based authentication
• Automatic reconnection with exponential backoff
• Health checks using WebSocket ping/pong
• Request and response streaming
• Simple deployment
• Zero external dependencies beyond Node.js packages

Architecture

Internet
    │
    ▼
+-------------+
| Cube Server |
+-------------+
       │ WebSocket
       ▼
+-------------+
| Cube Client |
+-------------+
       │
       ▼
Local Application
(127.0.0.1:PORT)

The server receives incoming HTTP requests and forwards them through a WebSocket tunnel to the client.

The client proxies those requests to a local HTTP service and sends the response back through the tunnel.

Installation

Clone Repository

git clone https://github.com/mhyar-nsi/cube-http.git
cd cube-http

Install Dependencies

npm install

Configuration

Server

Create a .env file:

TOKEN=my-secret-token
PORT=3000
PUBLIC_URL=https://example.com

Client

Create a .env file:

TOKEN=my-secret-token
SERVER_ADDRESS=example.com:3000

The TOKEN value must match on both sides.

Running the Server

cd server

node main.js

Server output:

Server listening on port 3000

Running the Client

Expose a local application running on port 8080:

cd client

node main.js http 8080

Example output:

Tunnel established: https://example.com

Request Flow

1. User sends an HTTP request to the public URL.
2. Cube Server receives the request.
3. Server forwards the request through WebSocket.
4. Cube Client receives the request.
5. Client sends the request to the local service.
6. Local service generates a response.
7. Client sends the response back.
8. Server returns the response to the user.

Reconnection

If the WebSocket connection is interrupted:

• The client automatically reconnects.
• Exponential backoff is used.
• Maximum retry delay is 30 seconds.

Authentication

Authentication is performed immediately after connection:

{
  "type": "auth",
  "token": "your-secret-token"
}

Connections with invalid tokens are rejected.

Environment Variables

Server

Variable	Description
TOKEN	Authentication token
PORT	HTTP/WebSocket server port
PUBLIC_URL	Public tunnel URL

Client

Variable	Description
TOKEN	Authentication token
SERVER_ADDRESS	Server address

Example

Local application:

localhost:5000

Client:

cd client

node main.js http 5000

Public URL:

https://example.com

Requests to the public URL will now be forwarded to:

http://127.0.0.1:5000

License

MIT