v1.0 Stable Release

Host Your Own Internet Gateway

Take full control by hosting your own Internet Gateway for enhanced privacy, security, and customization.

Powered by Advanced Technology

3 Internet Uplink Paths

Why Host Your Own Gateway?

Full Control

Complete control over your gateway infrastructure and data flow. You decide who connects.

Enhanced Privacy

Your data stays on your servers. No third-party dependencies or hidden logging.

Custom Configuration

Customize gateway settings, bandwidth limits, and features to your specific needs.

No Subscription

No monthly fees for the software. You only pay for your own server infrastructure.

No Dependencies

Operational independence. Your gateway works even if other parts of the internet are down.

System Requirements

OS
Linux (Ubuntu 22.04+ or Debian 12+ recommended)
Web Server
Nginx 1.22+ or Apache 2.4+ (Nginx + PHP-FPM recommended)
PHP
PHP 8.1+ with extensions: pdo, pdo_mysql, pdo_sqlite, curl, openssl, mbstring, json, sockets, pcntl
Database
MySQL 8.0+ or MariaDB 10.6+ (PostgreSQL also supported)
Security
Let's Encrypt SSL (free) or commercial SSL certificate. HTTPS is mandatory for secure communication.
Hardware
Minimum: 1 CPU Core, 1GB RAM, 10GB Storage
Recommended: 2 CPU Cores, 2GB RAM, 20GB NVMe Storage

Documentation & Guides

Step-by-step instructions to deploy your own MOSA Internet Gateway on a Linux server.

1 Understanding the Architecture

The MOSA Messenger does not care what programming language your server uses. Whether you build it in Node.js, Python, Go, or PHP—your gateway merely needs to expose the exact REST API endpoints and accept WebSocket frames in the specific JSON structures defined below.

Language Agnostic REST + WebSockets

2 Implementing the Status API

The first thing the app does is ping your server to verify it's a valid gateway and negotiate the WebSocket endpoint.

app.get('/api/v1/gateway/status', (req, res) => {
  res.json({
    status: 'online',
    version: '1.0',
    capabilities: {
      websocket_enabled: true,
      websocket_url: 'wss://gateway.yourdomain.com/ws'
    }
  });
});

3 Device Registration

When a new device connects, it will hit your `/api/v1/auth/register` endpoint with its Cryptographic Public Key. Your server must generate a unique API Key for that device and return it.

app.post('/api/v1/auth/register', (req, res) => {
  const { device_id, public_key } = req.body;
  const apiKey = generateSecureApiKey(); // e.g., crypto.randomBytes(32)
  
  // Save to Database: [device_id, public_key, apiKey]
  
  res.json({ api_key: apiKey });
});

4 Real-Time WebSocket Server (Node.js Example)

WebSockets are crucial for instant message delivery without draining battery life. Here is a basic implementation using the popular `ws` library in Node.js showing how to authenticate the app's initial payload and handle routing.

server.js
const WebSocket = require('ws');
const wss = new WebSocket.Server({ port: 8080 });

wss.on('connection', function connection(ws) {
  let isAuthenticated = false;
  let deviceId = null;

  ws.on('message', function incoming(data) {
    const payload = JSON.parse(data);

    // 1. Handle Authentication Frame
    if (payload.type === 'auth') {
      const user = verifyTokenInDatabase(payload.token);
      if (user) {
        isAuthenticated = true;
        deviceId = user.device_id;
        ws.send(JSON.stringify({ type: 'auth_success' }));
      } else {
        ws.close();
      }
      return;
    }

    // Require auth for all other frames
    if (!isAuthenticated) return;

    // 2. Handle Message Routing
    if (payload.type === 'message') {
      // Look up recipient's WebSocket connection and forward
      const recipientWs = activeConnections.get(payload.recipient_id);
      if (recipientWs) {
         recipientWs.send(JSON.stringify(payload));
      }
    }
  });
});

5 Handling Media and File Chunks

For files smaller than 5MB, the app will hit `POST /api/v1/files/send`. For larger files, it will utilize `POST /api/v1/files/chunk` to upload the payload in fragments. Voice message streams (`audio_stream`) are pushed directly over the WebSocket.

// File Chunking Logic
app.post('/api/v1/files/chunk', (req, res) => {
  const { message_id, chunk_index, total_chunks, chunk_data, is_last } = req.body;
  
  // Append base64 chunk_data to temp file
  appendChunkToTempFile(message_id, chunk_data);
  
  if (is_last) {
    assembleAndSaveFinalFile(message_id, total_chunks);
  }
  
  res.json({ success: true, chunk_index });
});

Setup Complete!

Your custom Internet Gateway is now successfully running. You can point your MOSA companion applications to https://gateway.yourdomain.com to start routing messages through your own secure infrastructure.

Custom Gateway API Specification

Build your own custom gateway software to bridge MOSA mesh networks with your bespoke internet infrastructure. Your software must implement these core endpoints.

Required HTTP Headers

Every incoming request from the messenger app expects your server to accept and enforce specific headers.

  • Content-Type: application/json
  • Accept: application/json
  • X-MOSA-Timestamp: <unix_timestamp>
  • Authorization: Bearer <API_KEY> (except for status and registration)

1. Gateway Status API

GET

The app calls this to check server health and negotiate WebSocket capabilities.

GET /api/v1/gateway/status

1. Authentication API

POST

Devices register with the gateway to obtain an API Key for subsequent requests.

Payload requires 'device_id' and 'public_key'. Security mode requires a cryptographic signature. Returns 'api_key'.

2. Send Message API

POST

Used to route an encrypted packet to a specific recipient through the gateway.

Requires Bearer Token. Payload: 'recipient_id', 'content' (encrypted Base64 payload), 'message_id', 'priority'.

3. Receive Messages API

GET

REST polling endpoint for clients pulling messages from the gateway's queue.

GET /api/v1/messages/receive/{userId}

Returns array of pending messages. Requires subsequent call to 'POST /api/v1/messages/acknowledge'.

File Transfer APIs

The app sends small files entirely, and chunks files over 5MB. Implement these endpoints to receive media.

  • POST POST /api/v1/files/send - used for files < 5MB using 'file_data' in Base64.
  • POST POST /api/v1/files/chunk - utilizes 'chunk_index', 'total_chunks', and 'is_last'.

WebSocket Real-Time Protocol

For immediate delivery and reduced polling overhead, MOSA clients maintain persistent WebSocket connections if available.

The app connects to the URI provided in your 'Gateway Status' response capabilities array under 'websocket_url'.

A. Connection & Auth Frame

After connecting to your ws:// or wss:// endpoint, the client sends an auth frame immediately.

{"type": "auth", "token": "API_KEY"}

B. Routing Frames

To send messages or WebRTC signaling data in real-time.

{"type": "message", "recipient_id": "...", "content": "..."}

C. Media Streams

Your server must handle forwarding 'audio_stream' continuous chunks and 'video_signal' WebRTC signaling frames.

Don't Want to Self-Host?

Use our official Internet Gateway at gateway.talivio.com. Fully managed, secure, and always up-to-date.
Need a higher rate limit? Contact [email protected] for custom quotas.

Use Official Gateway