Skip to content

README.md

Latest commit

 

History

History
254 lines (201 loc) · 9.44 KB

README.md

File metadata and controls

254 lines (201 loc) · 9.44 KB

🏠 NexusControl

Your complete homelab command center for Android

Monitor, manage, and automate all your servers from one beautiful app.

License: MIT Android Kotlin Jetpack Compose

✨ Features

📱 Device Management

  • Add servers, NAS, Raspberry Pi, routers, and more
  • Connect via SSH, Wake-on-LAN, or REST APIs (Home Assistant, Proxmox, TrueNAS, Pi-hole)
  • Quick-action chips for instant Terminal, SFTP, and WoL access
  • Long-press quick actions — Reboot, Shutdown, Wake, Terminal, Files, Edit, Delete via bottom sheet
  • Pull-to-refresh with live ping status for all devices
  • Search and filter across your entire fleet
  • Device grouping with collapsible sections

📊 Live Dashboard

  • Customizable tile grid with real-time data
  • Server Status — CPU, RAM, disk usage via SSH
  • Docker — Running/total container counts with progress bar
  • Pi-hole — Query & blocked counts with animated stats
  • Services — Systemd running/failed service counts
  • Ping Latency — Quality indicator (Excellent/Good/Fair/Poor)
  • Home Assistant — Entity state monitoring
  • Custom API — JSON key-value display from any endpoint
  • Community Tiles — Plugin architecture for user-created tiles (SSH command or API endpoint as data source)
  • Auto-refresh every 30 seconds with countdown timer
  • Live pulse indicator — Green pulsing dot shows the dashboard is alive
  • Spinning refresh icon animation during data fetches
  • Relative timestamps — "Just updated", "Updated 15s ago"
  • Per-tile error handling — Error overlays with warning icons on failed tiles
  • Failed tile count in header subtitle

💻 Multi-Tab SSH Terminal

  • Full interactive terminal with multiple concurrent sessions
  • Command history — Up/Down arrows to recall last 50 commands
  • Clear output — One-tap terminal clear
  • Tab-safe crash protection (deferred tab switching, SupervisorJob)
  • Connecting/disconnected state indicators with reconnect

📁 SFTP File Browser

  • Browse, upload, download, and edit remote files
  • Interactive breadcrumb path bar — Click any segment to jump
  • Copy, cut, paste between directories
  • Create files and folders
  • Inline file editor with monospace font
  • Transfer progress overlay

📝 Script Library & Scheduling

  • Create, organize, and execute bash/python scripts on devices
  • 19 pre-built templates — System info, updates, Docker, firewall, users, logs, backups, web server
  • Quick Insert chips — Tap to insert if, for, while, function, case, and more
  • Template gallery with one-tap import
  • Run scripts directly on any SSH device with live output
  • Script scheduling — Enable automated execution with cron presets:
    • Every 5m, 30m, Hourly, Daily 6am, Daily midnight, Weekly, Monthly
    • Custom cron expression support
    • Target device picker for scheduled runs
    • Powered by WorkManager for reliable background execution
  • Execution history — View all past script runs with:
    • Filter by: All / Completed / Failed
    • Expandable log cards with monospace output preview
    • Script name, device, exit code, duration, timestamp
    • One-tap delete or clear all

🔔 Notifications
  • Script execution notifications — Get notified when scheduled scripts complete or fail
    • Shows ✅/❌ status, script name, device, exit code, duration
    • Error output included on failure
  • Notification channels — Script Execution + Device Alerts (separate Android notification channels)

🔑 SSH Key Management

  • Settings → Security → SSH Keys — Dedicated key management screen
  • Generate RSA-2048 key pairs with custom names
  • Import existing PEM private keys
  • Key cards showing: name, type, SHA-256 fingerprint, public key preview, creation date
  • Copy public key to clipboard for pasting into authorized_keys
  • Delete keys with one tap
  • All private keys encrypted with Android Keystore

⚙️ Settings & Customization

  • Theme — System, Light, or Dark mode
  • Dynamic Colors — Material You wallpaper-based theming
  • Monitoring — Configurable refresh interval (10–300s)
  • Notifications — Device alerts & script results toggle

🎓 Guided Onboarding
  • 5-page introduction to all features
  • "Add Your First Device" interactive setup page:
    • Form fields for name, host, port, username, password
    • Security info banner about local encryption
    • "Add & Get Started" saves the device directly
    • "Skip for now" to set up later

🔒 Security & Privacy

  • All credentials encrypted with Android Keystore
  • SSH key private keys encrypted at rest
  • No accounts, no telemetry, no ads, no tracking
  • 100% open source — inspect every line of code

📋 Requirements

Requirement Minimum
Android 11+ (API 30)
Android Studio Ladybug or newer
JDK 17

🚀 Build Instructions

# 1. Clone the repository
git clone https://github.com/iTroy0/NexusControl.git

# 2. Open in Android Studio and let Gradle sync

# 3. Connect a device or start an emulator (API 30+)

# 4. Build & run
./gradlew assembleDebug

Or simply click Run ▶️ in Android Studio.

🛠 Tech Stack

Layer Technology
Language Kotlin 2.0
UI Jetpack Compose + Material 3 (Material You)
DI Hilt
Database Room
Preferences DataStore
Background WorkManager
Navigation Navigation Compose
SSH/SFTP SSHJ
Networking OkHttp + Retrofit
Serialization kotlinx.serialization
Security Android Keystore + BouncyCastle + EdDSA

🏗 Architecture

NexusControl follows Clean Architecture with three layers:

┌─────────────────────────────────────────┐
│  Presentation (Compose + ViewModels)    │
├─────────────────────────────────────────┤
│  Domain (Models + Repository Interfaces)│
├─────────────────────────────────────────┤
│  Data (Room, SSH, API, Security, DI)    │
└─────────────────────────────────────────┘
  • Unidirectional data flow — StateFlow → Compose → ViewModel → Repository
  • Dependency injection — Hilt modules for database, network, and security
  • Reactive data — Room Flow + StateFlow for live UI updates

📂 Project Structure

app/src/main/java/com/nexuscontrol/app/
├── data/               # Data layer
│   ├── local/          # Room database, DAOs, entities
│   ├── network/        # SSH, SFTP, API, WoL managers
│   ├── notification/   # Notification channels & helpers
│   ├── preferences/    # DataStore user preferences
│   ├── repository/     # Repository implementations
│   ├── security/       # Credential & SSH key encryption
│   ├── sftp/           # SFTP file operations
│   ├── ssh/            # SSH session management
│   └── worker/         # Background workers (script scheduling)
├── di/                 # Hilt dependency injection modules
├── domain/             # Domain layer
│   ├── model/          # Data models (Device, Script, Tile, AlertRule)
│   └── repository/     # Repository interfaces
├── navigation/         # Navigation graph & routes
├── presentation/       # UI layer
│   ├── common/         # Shared composables (LoadingState, EmptyState)
│   ├── dashboard/      # Dashboard screen & tile components
│   ├── devices/        # Device list, editor & quick actions
│   ├── onboarding/     # First-launch onboarding with setup
│   ├── scripts/        # Script library, editor, scheduling & history
│   ├── settings/       # App settings & SSH key management
│   ├── sftp/           # SFTP file browser & hub
│   └── terminal/       # Multi-tab SSH terminal
└── ui/theme/           # Material 3 theming & color system

📄 License

MIT License — see LICENSE

Built with ❤️ for the homelab community

No cloud. No accounts. No telemetry. Just you and your servers.

Buy Me A Coffee