📘 Introduction to Synexa

Key Concepts

• Container-Based Applications: Each app runs in an isolated Docker container
• WebRTC Streaming: Ultra-low latency video streaming directly to your browser
• Shared Storage: All your applications access the same file system
• Session Management: Seamless creation and management of application instances

How It Works

1. User logs into the Synexa dashboard
2. Clicks on an application (Terminal, Files, VLC, etc.)
3. API creates a new Docker container for that application
4. Container starts Xvfb (virtual display) and the application
5. GStreamer captures the display and encodes to H.264
6. WebRTC streams video/audio to the browser
7. User interacts via keyboard/mouse sent through WebRTC data channels

🚀 Quick Start

For Users

# 1. Visit the Synexa dashboard
open https://app.synexa.io

# 2. Create an account or log in

# 3. Click on any application to launch it

# 4. Start working!

For Self-Hosters

# 1. Clone the repository
git clone https://github.com/synexa/synexa.git
cd synexa

# 2. Start the full stack
./start-synexa.sh

# 3. Access the dashboard
open http://localhost:3000

Services

🏗️ Architecture

System Overview

Synexa is built as three independent repositories:

1. synexa-frontend

• Technology: React, TypeScript, Vite
• Purpose: Web UI with WebRTC client for streaming
• Features: Session management, video player, input handling

2. synexa-controlplane

• Technology: Go, Gin framework, Redis
• Purpose: REST API for session orchestration
• Features: Container lifecycle, authentication, WebRTC signaling

3. synexa-images

• Technology: Docker, GStreamer, Xvfb
• Purpose: Base image + application images
• Features: WebRTC server, display capture, input injection

Component Diagram

┌─────────────┐
│   Browser   │
│  (WebRTC)   │
└──────┬──────┘
       │
       ▼
┌─────────────┐      ┌──────────────┐
│  Frontend   │─────▶│ Control Plane│
│  (React)    │      │   (Go API)   │
└─────────────┘      └───────┬──────┘
                             │
                             ▼
                     ┌───────────────┐
                     │ Docker Engine │
                     └───────┬───────┘
                             │
        ┌────────────────────┼────────────────────┐
        ▼                    ▼                    ▼
   ┌─────────┐         ┌─────────┐         ┌─────────┐
   │Terminal │         │  Files  │         │   VLC   │
   │Container│         │Container│         │Container│
   └─────────┘         └─────────┘         └─────────┘
        │                    │                    │
        └────────────────────┴────────────────────┘
                             │
                      ┌──────▼──────┐
                      │Shared Volume│
                      │/home/user   │
                      └─────────────┘

💻 Terminal Application

Overview

Full-featured xterm terminal with command-line access to your cloud environment.

Features

• Full color support (256 colors + true color)
• Unicode and emoji support
• Copy/paste via context menu
• Automatic font scaling
• Persistent bash history

Keyboard Shortcuts

📁 File Manager

Overview

Thunar file manager with GVFS support for managing your cloud storage.

Features

• Drag-and-drop file operations
• Context menu integration
• File associations (open .mp4 in VLC)
• Thumbnail previews for images/videos
• Network share support via GVFS

File Associations

Double-clicking certain file types automatically opens them in the appropriate application:

🎬 VLC Media Player

Overview

The world's most popular media player, streaming in your browser.

Supported Formats

• Video: MP4, MKV, AVI, MOV, WMV, FLV, WebM
• Audio: MP3, WAV, FLAC, OGG, AAC, M4A
• Subtitles: SRT, ASS, SSA, VTT

Opening Files

# Method 1: Double-click in File Manager
# Just double-click any video/audio file in Files app

# Method 2: Via API
curl -X POST http://localhost:8081/api/v1/users/demo/open-with \
  -H "Content-Type: application/json" \
  -d '{
    "app": "vlc",
    "file": "/home/neximo/files/video.mp4",
    "sessionId": "files-demo"
  }'

🌐 WebRTC Streaming

How It Works

Synexa uses WebRTC for ultra-low latency streaming:

1. Display Capture: Xvfb creates virtual display (1920x1080)
2. Video Encoding: GStreamer captures and encodes to H.264
3. RTP Streaming: Video sent via RTP over UDP
4. WebRTC: Browser receives stream via WebRTC peer connection
5. Input: Mouse/keyboard sent back via data channels

Performance

💾 Persistent Storage

Shared File System

All applications share the same storage volume mounted at /home/neximo/files.

Docker Compose

volumes:
  - ./user-data/demo:/home/neximo/files

Kubernetes

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: user-demo-files
spec:
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 10Gi

📡 Sessions API

Create Session

POST /api/v1/users/:userID/sessions
Content-Type: application/json

{
  "app": "terminal",
  "sessionId": "my-terminal"
}

Response:
{
  "session_id": "my-terminal",
  "proxy_url": "http://localhost:8081/proxy/token",
  "token": "jwt-token-here",
  "container_id": "abc123"
}

List Sessions

GET /api/v1/users/:userID/sessions

Response:
[
  {
    "session_id": "terminal-1",
    "app": "terminal",
    "status": "running",
    "created_at": "2026-01-06T10:00:00Z"
  }
]

Delete Session

DELETE /api/v1/users/:userID/sessions/:sessionID

Response:
{
  "message": "Session deleted successfully"
}

🐳 Docker Compose Deployment

Setup

# Clone repositories
git clone https://github.com/synexa/synexa-frontend
git clone https://github.com/synexa/synexa-controlplane
git clone https://github.com/synexa/synexa-images

# Build images
cd synexa-images
./build.sh

# Start services
cd ..
./start-synexa.sh

Environment Variables

# .env.fullstack
FRONTEND_PORT=3000
API_PORT=8081
JWT_SECRET=your-secret-key
VIDEO_BITRATE=2000
TERMINAL_PORT=8083
FILES_PORT=8084
VLC_PORT=8085

☸️ Kubernetes Deployment

Prerequisites

• Kubernetes cluster (1.24+)
• kubectl configured
• Helm 3.0+

Install

# Add Helm repository
helm repo add synexa https://charts.synexa.io
helm repo update

# Install
helm install synexa synexa/synexa \
  --set domain=app.synexa.io \
  --set storage.class=nfs-client \
  --set replicas.api=3

# Check status
kubectl get pods -n synexa