1ngaOS - P2P Network Platform

1ngaOS is a peer-to-peer network platform built with Rust and libp2p, designed to run on mobile devices (iOS/Android) and desktop platforms (Linux/Windows/macOS).

Features

• ✅ P2P Networking: Built on libp2p with Kademlia DHT, mDNS discovery, and Gossipsub
• ✅ Cross-Platform: Supports Linux, Windows, macOS, Android, and iOS
• ✅ REST API: HTTP API for network management and node operations
• ✅ CLI Tool: Command-line interface for node initialization and management
• ✅ Interactive Dashboard: Beautiful terminal UI with device info, performance graphs, and node scaling recommendations
• ✅ Service Discovery: Automatic peer discovery via mDNS and Kademlia DHT
• ✅ Message Broadcasting: Gossipsub for pub/sub messaging
• ✅ Direct Messaging: Request-response protocol for peer-to-peer communication

Installation

macOS Installation

Option 1: Using the Installation Script (Recommended)

cd apps/backend/services/wangos
./install.sh

This will:

• Build the release version of the CLI
• Install it to ~/.local/bin/wangos (CLI) and ~/.local/bin/wangos-service (service)
• Check if the directory is in your PATH

If ~/.local/bin is not in your PATH, add this to your ~/.zshrc:

export PATH="$HOME/.local/bin:$PATH"

Then reload your shell:

source ~/.zshrc

Option 2: Manual Installation

1. Build the release version:

   cd apps/backend/services/wangos
   cargo build --release --bin wangos-cli

2. Install to a directory in your PATH:

   Option A: Install to /usr/local/bin (requires sudo):

   sudo cp target/release/wangos-cli /usr/local/bin/wangos
   sudo chmod +x /usr/local/bin/wangos
   # Also install service
   sudo cp target/release/wangos /usr/local/bin/wangos-service
   sudo chmod +x /usr/local/bin/wangos-service

   Option B: Install to ~/.local/bin (no sudo required):

   mkdir -p ~/.local/bin
   cp target/release/wangos-cli ~/.local/bin/wangos
   chmod +x ~/.local/bin/wangos
   # Also install service
   cp target/release/wangos ~/.local/bin/wangos-service
   chmod +x ~/.local/bin/wangos-service
      
   # Add to PATH if not already there
   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
   source ~/.zshrc

3. Verify installation:

   wangos --help

Option 3: Use Directly (No Installation)

You can also run the CLI directly without installing:

cd apps/backend/services/wangos
./target/release/wangos-cli --help

Or create an alias in your ~/.zshrc:

alias wangos="$HOME/work/afrisync/apps/backend/services/wangos/target/release/wangos-cli"

Quick Start

Interactive Dashboard

Launch the interactive terminal dashboard to monitor device information, performance metrics, and get node scaling recommendations:

wangos dashboard

Dashboard Features:

• Overview Tab (1): Device information, CPU/Memory usage gauges, and node scaling recommendations
• Performance Tab (2): Real-time graphs for CPU, Memory, and Network usage
• Nodes Tab (3): List of running nodes with status, port, and PID information

Controls:

• 1, 2, 3 - Switch between tabs (Overview, Performance, Nodes)
• ↑, ↓ - Navigate node list (in Nodes tab)
• q or Esc - Exit dashboard

Node Scaling Recommendations: The dashboard automatically calculates:

• Recommended Nodes: Conservative estimate (70% of available resources)
• Maximum Nodes: Based on available memory and CPU cores
• Resource Estimates: Memory (~100MB) and CPU (~0.1 cores) requirements per node

Customize Refresh Rate:

# Refresh every 500ms (faster updates)
wangos dashboard --refresh 500

# Refresh every 2000ms (slower updates, less CPU usage)
wangos dashboard --refresh 2000

Initialize a Node

# Initialize a new node
wangos init --name my-node --platform macos

# Or with a bootstrap node
wangos init --name my-node --platform macos --bootstrap /ip4/192.168.1.100/tcp/9001/p2p/12D3KooW...

Run a Node

# Run in background (recommended)
wangos run --name my-node

# Or run in foreground
wangos run --name my-node --foreground

# Run with specific port
wangos run --name my-node --port 8018

Network Initialization (Multiple Devices)

# Discover devices on local network
wangos network-init

# Discover and initialize on other devices
wangos network-init --initialize

# Auto-start nodes after initialization
wangos network-init --initialize --auto-start

Manage Nodes

# List all running nodes
cityos list

# List with details
cityos list --detailed

# Stop a specific node
cityos stop --name my-node

# Stop all nodes
cityos stop-all

# Clean up stopped or stale nodes (keeps only running nodes)
cityos clean

# Force clean (removes all nodes, including running ones)
cityos clean --force

Check for Updates

# Check for new version updates
cityos version

# Check using custom version service URL
cityos version --check-url https://api.example.com/version

The version command will:

• Display your current version and protocol version
• Check GitHub releases for the latest version
• Warn if an update is available
• Provide download and changelog links

Start the Service (Full Service Mode)

# Set environment variables
export DATABASE_URL="postgresql://postgres:postgres@localhost:5432/wanga_cityos"
export P2P_ENABLED=true
export P2P_LISTEN_ADDRESSES="/ip4/0.0.0.0/tcp/0"

# Run the service
wangos-service

Using Docker

# Build the image
docker build -t cityos .

# Run the container
docker run -p 8017:8017 \
  -e DATABASE_URL="postgresql://postgres:[email protected]:5432/wanga_cityos" \
  -e P2P_ENABLED=true \
  cityos

Configuration

1ngaOS can be configured via environment variables:

Server Configuration

• HOST: Server host (default: 0.0.0.0)
• PORT: Server port (default: 8017)

Database Configuration

• DATABASE_URL: PostgreSQL connection string (default: postgresql://postgres:postgres@localhost:5432/wanga_cityos)

P2P Configuration

• P2P_ENABLED: Enable P2P networking (default: true)
• P2P_LISTEN_ADDRESSES: Comma-separated listen addresses (default: /ip4/0.0.0.0/tcp/0)
• P2P_BOOTSTRAP_NODES: Comma-separated bootstrap node addresses
• P2P_ENABLE_MDNS: Enable mDNS discovery (default: true)
• P2P_ENABLE_KADEMLIA: Enable Kademlia DHT (default: true)
• P2P_ENABLE_GOSSIPSUB: Enable Gossipsub pub/sub (default: true)

Tracing Configuration

• TRACING_ENABLED: Enable OpenTelemetry tracing (default: false)
• OTEL_EXPORTER_OTLP_ENDPOINT: OpenTelemetry collector endpoint

Service Registration

• SERVICE_NAME: Service name for registration (default: cityos)
• SERVICE_URL: Service URL for registration
• REDIS_URL: Redis connection string for service registry

API Endpoints

Health Check

GET /api/v1/health

Get Network Information

GET /api/v1/network

Get Local Peer ID

GET /api/v1/peer-id

Broadcast Message

POST /api/v1/broadcast
Content-Type: application/json

{
  "message": "Hello, 1ngaOS!",
  "topic": "cityos"
}

Send Direct Message

POST /api/v1/send
Content-Type: application/json

{
  "peer_id": "12D3KooW...",
  "message": "Hello, peer!"
}

Dial Peer

POST /api/v1/dial
Content-Type: application/json

{
  "address": "/ip4/192.168.1.100/tcp/9001/p2p/12D3KooW..."
}

CLI Commands

Initialize Node

wangos init [OPTIONS]

Options:
  -n, --name <NAME>        Node name
  -p, --platform <PLATFORM>  Platform (linux, windows, macos, android, ios)
  -o, --output <OUTPUT>    Output directory (default: ".")
  -b, --bootstrap <BOOTSTRAP>  Bootstrap node address

Show Node Information

cityos info [OPTIONS]

Options:
  -c, --config <CONFIG>   Configuration file (default: ".cityos/config.toml")

Run Node (Background)

wangos run [OPTIONS]

Options:
  -n, --name <NAME>        Node name (must be initialized first)
  -c, --config <CONFIG>    Node configuration file
  -p, --port <PORT>        Port to run on (auto-detects if not specified)
  -f, --foreground         Run in foreground (don't detach)

List Running Nodes

cityos list [OPTIONS]

Options:
  -d, --detailed           Show detailed information

Stop Node

cityos stop [OPTIONS]

Options:
  -n, --name <NAME>        Node name to stop

Stop All Nodes

cityos stop-all

Network Initialization

wangos network-init [OPTIONS]

Options:
  -p, --port <PORT>        Port to scan for 1ngaOS nodes (default: 8017)
  -t, --timeout <TIMEOUT>  Timeout for network scan in milliseconds (default: 500)
  -i, --initialize         Initialize nodes on discovered devices
  -a, --auto-start         Auto-start nodes after initialization

This command:

• Scans the local network for devices
• Discovers existing 1ngaOS nodes
• Provides bootstrap addresses for new nodes
• Optionally initializes 1ngaOS on other devices
• Helps set up a P2P network across multiple devices

Platform Support

Desktop Platforms

• Linux: Native binary support
• Windows: Native binary support
• macOS: Native binary support

Mobile Platforms

• Android: Can be compiled as a native library or used via FFI
• iOS: Can be compiled as a framework or used via FFI

Development

Build

cargo build --release

Run Tests

cargo test

Run with Logging

RUST_LOG=debug cityos

Architecture

1ngaOS uses libp2p for P2P networking with the following protocols:

• Kademlia DHT: Peer discovery and content routing
• mDNS: Local network discovery
• Gossipsub: Pub/sub messaging
• Request-Response: Direct peer-to-peer communication
• Ping: Connection health checks

License

MIT