Pathway

Self-Hosted SMS & USSD Gateway

Transform your Android device into a powerful local API server

Overview

Pathway is a robust, self-hosted SMS and USSD Gateway solution that turns your Android device into a local API server. It consists of two main components:

Android Gateway App - Runs directly on your phone
Desktop Dashboard - Manage everything from your computer

Perfect for businesses, developers, and enthusiasts who need reliable SMS automation without depending on cloud services.

View Architecture Documentation for detailed system design and data flow diagrams.

Project Structure

pathway/
├── phone/          # Android Gateway Application
│   └── Built with SvelteKit + Capacitor
│       Runs local HTTP server (http://IP:8080)
│
└── desktop/        # Management Dashboard
    └── Built with SvelteKit + Tauri
        Available as native desktop apps & web build

Component Details

Component	Technology	Description
`/phone`	SvelteKit + Capacitor	Android Gateway app that runs a local HTTP server on your device to expose SMS and USSD capabilities
`/desktop`	SvelteKit + Tauri	Management Dashboard for sending campaigns, viewing logs, and managing the system. Available for Windows, macOS, Linux

Key Features

Android Gateway (`/phone`)

Core Functionality

REST API: Simple endpoints for /sms and /ussd
Dual SIM Support: Intelligent SIM selection with global defaults
Unicode Support: Native support for Bangla and other Unicode languages (Multipart SMS)

Reliability Features

24/7 Persistence: Keep screen on to prevent device sleep
Battery Optimization: Bypass Android's background process killing
Test Console: In-app API verification tool

Desktop Dashboard (`/desktop`)

Platform Support

Native Desktop Apps: Built with Tauri for Windows, macOS, and Linux
No CORS Restrictions: Direct communication with gateways
Multi-Device Support: Connect and manage multiple Android gateways simultaneously

Advanced Features

Real-time Status: Automatic polling shows device Online/Offline status
Smart SMS Distribution: Round-robin load balancing across devices
Activity Logs: Detailed per-device delivery logs
Modern UI: Premium dark-mode interface built with Svelte 5 and Shadcn

Smart Distribution Example

When sending 100 messages with 2 connected devices:

Device A: 50 messages (Round-robin distribution)
Device B: 50 messages (Round-robin distribution)

Benefits: Faster bulk sending & prevents carrier rate-limiting on single SIM

Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

Requirement	Version	Purpose
Node.js	20+	JavaScript runtime
pnpm	Latest	Package manager
Java	17+	Android builds
Rust	Latest	Tauri desktop builds

Step 1: Android Gateway Setup

# Navigate to phone directory
cd phone

# Install dependencies
pnpm install

# Run on Android Device (requires USB debugging enabled)
pnpm run dev:android

Configuration Steps

Once the app is running on your phone:

Start Server: Tap the "Start Server" button
Note Connection Details: Check the IP address and Port (default: 8080)
Configure SIM: Set your default SIM in the "SIM Configuration" card
Enable Background Running: Use the "Power" and "Zap" icons to keep the app active

Tip: Make sure your phone and computer are on the same network for local API access.

Step 2: Desktop Dashboard Setup

# Navigate to desktop directory
cd desktop

# Install dependencies
pnpm install

# Option 1: Start Web Development Server
pnpm run dev

# Option 2: Start Tauri Development (native desktop app)
pnpm run tauri:dev

# Option 3: Build Tauri Desktop App for production
pnpm run tauri:build

API Usage

The Gateway exposes a standardized JSON API for easy integration.

Send SMS

Endpoint: POST /sms

Request Body:

{
  "number": "01700000000",
  "message": "Hello from Pathway!"
}

Example with cURL:

curl -X POST http://192.168.1.100:8080/sms \
  -H "Content-Type: application/json" \
  -d '{
    "number": "01700000000",
    "message": "Hello from Pathway!"
  }'

Run USSD

Endpoint: POST /ussd

Request Body:

{
  "code": "*124#"
}

Example with cURL:

curl -X POST http://192.168.1.100:8080/ussd \
  -H "Content-Type: application/json" \
  -d '{
    "code": "*124#"
  }'

Note: The API uses the app's globally configured "Preferred SIM" setting.

Automated Builds (CI/CD)

GitHub Actions automatically build artifacts on push:

Component	Trigger	Output
Android App	Push to `/phone`	`app-debug.apk` (Debug APK via Capacitor)
Desktop App	Push to `/desktop`	Static site zip + Native executables (Windows, macOS, Linux)

Creating Releases

Releases are automatically created when you push a version tag.

Quick Start

Create a version tag (following semantic versioning):
```
git tag v1.0.0
```
Push the tag to GitHub:
```
git push origin v1.0.0
```
Automatic Build - The release workflow will:
- Build Android APK (app-debug.apk)
- Build Desktop static site (desktop-build.zip)
- Build native apps for Windows, macOS, Linux
- Create GitHub Release with auto-generated notes
- Attach all artifacts for download

Release Artifacts

Each release includes the following downloadable files:

Artifact	Platform	Description
`app-debug.apk`	Android	Gateway application (install directly)
`desktop-build.zip`	Web	Static site (extract and host)
`pathway-desktop_*.AppImage`	Linux	Portable executable (no installation)
`pathway-desktop_*.deb`	Linux	Debian package
`Pathway Desktop.exe`	Windows	Portable executable (no installation)
`Pathway Desktop_*-setup.exe`	Windows	NSIS installer
`Pathway Desktop_*.dmg`	macOS	Disk image

Quick Release Commands

# Create and push a new release
git tag v1.0.0 && git push origin v1.0.0

# Create a pre-release version
git tag v1.0.0-beta.1 && git push origin v1.0.0-beta.1

# List all existing tags
git tag -l

# Delete a tag locally and remotely (if needed)
git tag -d v1.0.0
git push origin --delete v1.0.0

Limitations

Android Gateway Limitations

Limitation	Description	Workaround
Battery & Power Management	Android may kill the app in the background despite optimization settings	Keep device plugged in and disable battery optimization for the app
Network Requirements	Both phone and desktop must be on the same local network	Use VPN or port forwarding for remote access
Phone Must Stay Powered	The device needs to remain on and connected to power for 24/7 operation	Use a dedicated device or ensure continuous power supply
Android Version	Requires Android 6.0 (API level 23) or higher	Use a supported device
Permissions	Requires SMS and Phone permissions at runtime	Grant all requested permissions during setup

Desktop Dashboard Limitations

Limitation	Description	Workaround
Local Network Only	Default setup works only on local network	Configure network routing or VPN for remote access
No SMS Reception	Currently only supports sending SMS, not receiving	Future feature consideration
Manual Device Management	Devices must be manually added to the dashboard	Keep track of device IPs (consider static IP assignment)
No Cloud Sync	All data is stored locally on the desktop app	Backup desktop app data regularly

Technical Limitations

Limitation	Description	Impact
Carrier Rate Limits	Mobile carriers may throttle or block bulk SMS sending	Use multiple devices or spread sending over time
SMS Character Limits	Standard SMS: 160 characters (Unicode: 70 characters)	Long messages automatically split into multiple parts
USSD Session Timeout	USSD sessions may timeout based on carrier settings	Execute USSD codes promptly
No End-to-End Encryption	API communication is not encrypted by default	Use on trusted networks or implement HTTPS
No Built-in Analytics	Limited analytics and reporting features	Export logs for external analysis

Known Issues

Android 12+: Some aggressive battery optimization requires manual intervention in device settings
Dual SIM: SIM switching may have a slight delay depending on the device
Background Restrictions: Some Android manufacturers (Xiaomi, Huawei, etc.) have additional restrictions that need to be disabled manually

Tip: For production use, we recommend using a dedicated Android device that stays powered and connected to ensure maximum reliability.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Built with SvelteKit
Mobile app powered by Capacitor
Desktop app powered by Tauri
UI components from Shadcn-Svelte

Generative AI

This project utilizes code created by the following models: Gemini 3 Flash, Gemini 3 Pro Preview, Claude 4.5 Opus. All code generated by them have been throughly inspected however problems may arise. No "vibe coding" was done. A human wrote majority of the code. AI was utilized to speedup development of simple features.

Made with love by the Pathway Team

Star us on GitHub | Report Bug | Request Feature

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
desktop		desktop
docs		docs
phone		phone
website		website
LICENSE		LICENSE
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation