obeoneorg/simplex-client

•Updated 21 days ago

Image

2.4K

obeoneorg/simplex-client repository overview

⁠SimpleX Web Client

A web-based client for SimpleX Chat⁠, built with Vue 3 and backed by a Python FastAPI server that bridges the browser to the simplex-chat daemon's WebSocket API.

flowchart TB
    A["Browser\nVue 3 + Pinia"] -->|"HTTP & WS"| B
    B["FastAPI Backend"] -->|"WebSocket API"| C
    C["simplex-chat Daemon"] -->|"Events"| B
    B -->|"Normalised Events"| A
    D["simplex-ws-proxy\n(optional)"] -.->|"Multiplex"| C
    B -.->|"WS + broadcast"| D

⁠🚀 Features

Feature	Description
Real-time messaging	WebSocket event stream from daemon to browser with per-chat message storage
Contacts and groups	List, connect, accept/reject requests, join groups
Message history	Lazy-loaded conversation history via daemon API
File transfers	Upload, send, receive, and download files through the UI
Optional auth	HTTP Basic authentication via environment variables
Proxy support	Works with simplex-ws-proxy⁠ for shared daemon access
Docker ready	Multi-stage Dockerfile, published as `obeoneorg/simplex-client`
CLI launcher	Installable `simplex-ws-client` command that runs both servers

⁠📋 Prerequisites

Python 3.11+
Node.js (LTS recommended)
uv⁠ for Python package management
A running simplex-chat daemon with WebSocket enabled:

simplex-chat --websocket 5225

⁠📁 Project Structure

simplex-client/
  backend/                  # Python FastAPI server
    main.py                 # App, REST API, WS endpoint
    simplex_client.py       # Async WS client to daemon
    state.py                # In-memory dataclasses
    healthcheck.py          # Docker HEALTHCHECK script
    tests/                  # pytest test suite
  frontend/                 # Vue 3 + Vite + Pinia
    src/stores/chatStore.js # Central Pinia store
    src/composables/        # useApi, useWebSocket
    src/components/         # UI components
  src/simplex_ws_client/    # CLI tool (pip/uv installable)
  Dockerfile                # Multi-stage production build

⁠📦 Installation

⁠Docker (recommended)

docker run -d \
  -p 8000:8000 \
  -e SIMPLEX_WS_URL=ws://simplex-chat:5225 \
  -e AUTH_USERNAME=admin \
  -e AUTH_PASSWORD=changeme \
  -v simplex-files:/data \
  obeoneorg/simplex-client

Or with Docker Compose:

services:
  simplex-client:
    image: obeoneorg/simplex-client
    ports:
      - "8000:8000"
    environment:
      SIMPLEX_WS_URL: ws://simplex-chat:5225
      FILES_DIR: /data
      AUTH_USERNAME: admin
      AUTH_PASSWORD: changeme
    volumes:
      - simplex-files:/data

volumes:
  simplex-files:

⁠Local

⁠Backend

cd backend
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt

⁠Frontend

Note (arm64 / Docker): Use --ignore-scripts to avoid known esbuild issues on arm64 environments.

cd frontend
npm install --ignore-scripts

⁠CLI Tool

# Install globally (editable -- changes reflected immediately)
uv tool install --editable .
# or
pipx install .

# Launch both servers
simplex-ws-client

# Force reinstall dependencies in XDG directories
simplex-ws-client --setup

⁠⚙️ Configuration

Create a .env file in the backend/ directory:

# simplex-chat daemon WebSocket URL
# CLI override: --simplex-url ws://host:port
SIMPLEX_WS_URL=ws://localhost:5225

# Directory for received/uploaded files
FILES_DIR=~/simplex-files

# FastAPI bind host and port
# CLI overrides: --host, --port
HOST=0.0.0.0
PORT=8000

# Number of history messages to fetch per conversation
HISTORY_COUNT=100

# Subscribe to responses from all proxy clients
# Only relevant with simplex-ws-proxy
# CLI override: --broadcast-responses
BROADCAST_RESPONSES=false

# Optional HTTP Basic authentication
# Set both to enable; leave unset to disable
# AUTH_USERNAME=admin
# AUTH_PASSWORD=changeme

⁠Using with simplex-ws-proxy

If you run a simplex-ws-proxy⁠ in front of the daemon (to multiplex several clients on a single daemon connection), point SIMPLEX_WS_URL at the proxy and optionally enable BROADCAST_RESPONSES:

SIMPLEX_WS_URL=ws://proxy-host:5226
BROADCAST_RESPONSES=true

When BROADCAST_RESPONSES=true, the backend connects to the proxy with ?broadcast_responses=true, subscribing to responses routed to any other client on the same proxy. This is useful when the backend needs a complete view of all activity on a shared proxy (e.g. to maintain accurate in-memory state when multiple tools share the same daemon connection). Broadcast echoes of the backend's own commands are automatically deduplicated.

⁠🔧 Usage

Start each component in the following order:

⁠1. simplex-chat daemon

simplex-chat --websocket 5225

⁠2. Backend (FastAPI)

cd backend
source .venv/bin/activate
uvicorn main:app --reload

Backend will be available at: http://localhost:8000

⁠3. Frontend (Vue 3 + Vite)

cd frontend
npm run dev

Frontend will be available at: http://localhost:5173

⁠🛠️ Development Commands

Command	Description
`uvicorn main:app --reload`	Start backend with hot reload
`python main.py --port 8001`	Start backend with CLI args
`npm run dev`	Start frontend dev server
`npm run build`	Build frontend for production
`npm run preview`	Preview production build locally
`python -m pytest tests/`	Run backend test suite
`docker build -t simplex-ws-client .`	Build Docker image

⁠📄 License

This project is licensed under the MIT License⁠.

Built by obeone⁠

Tag summary

Recent tags

Content type

Image

Digest

sha256:a4814a56c…

Size

65.8 MB

Last updated

21 days ago

docker pull obeoneorg/simplex-client