🏠 NexusControl

Your complete homelab command center for Android

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

---

✨ 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.