Transform your phone into a powerful Stream Deck for macOS
NodeDeck is a modern Stream Deck alternative that lets you control your Mac from any device with a web browser. Features a beautiful PWA interface, automatic QR code connection, and comprehensive system controls.
- Volume controls (up/down/mute)
- Media playback (play/pause/next/previous)
- System audio management
- Spotlight search (⌘+Space)
- Launchpad (F4)
- Mission Control (Ctrl+↑)
- Show Desktop (F11)
- Lock Screen (Ctrl+⌘+Q)
- Force Quit applications (⌘+⌥+Esc)
- Progressive Web App (PWA) - install on your phone
- Dark theme with gradient buttons
- Responsive 3x3 grid layout
- Haptic feedback support
- Auto-connection via QR code
- Screenshot capture
- Brightness controls
- Menu bar integration
- Theme-adaptive tray icons
- Permission management system
- Download the latest
NodeDeck-1.0.0-arm64.dmgfrom releases - Double-click to mount and drag to Applications
- Launch NodeDeck from Applications or Launchpad
- Click the menu bar icon and scan the QR code with your phone
- Start controlling your Mac! 🎉
# Clone the repository
git clone <repository-url>
cd nodedeck
# Install dependencies and build
npm run install:all
npm run dist:mac
# Find your built app at:
# nodedeck-electron/dist/NodeDeck-1.0.0-arm64.dmg- macOS 10.15+ (for system control features)
- Node.js 18+ (for building from source)
- Accessibility permissions (automatically prompted)
- Launch NodeDeck - The app runs in your menu bar (top-right corner)
- Grant Permissions - NodeDeck will guide you through enabling Accessibility permissions
- Connect Device - Click the tray icon to show QR code, scan with your phone
- Install PWA - Add the web app to your phone's home screen for the best experience
- Phone Control: Use the 12-button grid interface on your connected device
- Multiple Devices: Share the QR code to connect multiple phones/tablets
- Auto-Reconnect: Devices automatically reconnect when in range
NodeDeck consists of three integrated components:
- 📱 Client (
nodedeck-client): React PWA with responsive interface - 🖥️ Server (
nodedeck-server): Express.js backend for standalone mode - ⚡ Electron (
nodedeck-electron): Desktop app with embedded server
- Menu bar application with embedded server
- Automatic port detection and QR code generation
- Theme-adaptive tray icons
- Built-in permission management
# Run server separately
cd nodedeck-server && npm start
# Run client development server
cd nodedeck-client && npm run dev# Install Node.js
brew install node
# Verify versions
node --version # 18.0+
npm --version # 8.0+# Install all dependencies
npm run install:all
# Start development servers
npm run dev:client # React dev server
npm run dev:server # Express server
npm run dev:electron # Electron app# Build everything
npm run build:all
# Platform-specific builds
npm run dist:mac # macOS DMG
npm run dist:win # Windows installer
npm run dist:linux # Linux packages
# Development builds (faster)
npm run pack:mac # Unpacked app bundle- 📘 Build Guide - Comprehensive building instructions
- 🔧 API Reference - Server API documentation
- 📱 Client Guide - PWA setup and features
- Windows Support - Full Windows compatibility
- Custom Actions - User-defined system commands
- Themes - Multiple UI themes and customization
- Plugins - Extensible plugin system
- Cloud Sync - Sync settings across devices
- Multi-Monitor - Enhanced multi-display support
We welcome contributions! Here's how to get started:
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes and test thoroughly
- Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
- Follow existing code style and patterns
- Test on macOS before submitting
- Update documentation for new features
- Ensure all builds pass:
npm run build:all
This project is licensed under the MIT License - see the LICENSE file for details.
- Electron - Cross-platform desktop app framework
- React - UI library for the web interface
- Socket.IO - Real-time bidirectional communication
- Vite - Fast build tool and dev server
- AppleScript - macOS system automation
App won't start?
# Rebuild native dependencies
cd nodedeck-electron && npm rebuildPermission errors?
- NodeDeck will automatically guide you to fix Accessibility permissions
- Go to: System Settings > Security & Privacy > Accessibility
Connection issues?
- Check that your devices are on the same network
- Try refreshing the QR code
- Ensure firewall isn't blocking the connection
- 🐛 Bug Reports: Open an issue with reproduction steps
- 💡 Feature Requests: Describe your idea in a new issue
- 💬 Questions: Use GitHub Discussions for general questions
Made with ❤️ for the macOS community
Transform your mobile device into a powerful remote control for your Mac today!