# Shell Mirror **Access your Mac terminal from any device, securely.** Perfect for mobile coding with Claude Code CLI, Gemini CLI, and any shell tool. --- ## What is Shell Mirror? Shell Mirror lets you access your Mac terminal from any web browser on any device (phone, tablet, laptop). It uses WebRTC for fast, peer-to-peer terminal mirroring with Google OAuth 2.0 authentication to keep your terminal secure. ### Key Features ✅ **Secure Access** - Google OAuth 2.0 authentication ✅ **WebRTC Connection** - Fast, direct peer-to-peer terminal mirroring ✅ **Multiple Sessions** - Create and manage multiple terminal sessions ✅ **Dashboard** - Visual dashboard to manage connected agents and sessions ✅ **Mobile-Friendly** - Optimized for mobile coding (perfect for AI coding tools) ✅ **NPM Package** - Easy installation via `npm install -g shell-mirror` ✅ **Auto-Start** - Mac agent auto-starts and registers with cloud server --- ## 🏗️ Architecture ``` ┌─────────────────────────────────────────────────────────────┐ │ User's Browser │ │ (https://shellmirror.app) │ │ ┌──────────────────────────────────────┐ │ │ │ Dashboard │ Terminal Interface │ │ │ └──────────────────────────────────────┘ │ └────────────────────┬────────────────────────────────────────┘ │ Google OAuth 2.0 Authentication │ ┌────────────────▼────────────────────────────┐ │ Heroku WebSocket Signaling Server │ │ (wss://shell-mirror-[...].herokuapp.com) │ │ │ │ • WebRTC signaling (SDP/ICE exchange) │ │ • Agent discovery & registration │ │ • Dashboard real-time updates │ └────────────────┬────────────────────────────┘ │ WebSocket Connection (both ways) │ ┌────────────────▼────────────────────────────┐ │ Mac Agent (User's Computer) │ │ │ │ • Auto-starts on login │ │ • Registers with cloud server │ │ • Manages multiple terminal sessions │ │ • WebRTC peer connection to browser │ └─────────────────────────────────────────────┘ │ Terminal Sessions │ ┌──────┴──────┐ │ Terminal │ │ (node-pty) │ └─────────────┘ ``` ### Components 1. **Frontend (TMDHosting)**: Static website at https://shellmirror.app 2. **WebSocket Server (Heroku)**: Node.js signaling server for WebRTC 3. **PHP Backend (TMDHosting)**: Agent registration and authentication APIs 4. **Mac Agent**: Local terminal mirroring agent (npm package) 5. **Dashboard**: Real-time agent and session management interface --- ## 🚀 Quick Start ### For Users (NPM Package) ```bash # Install globally npm install -g shell-mirror # Run setup wizard (configures Google OAuth) shell-mirror setup # Start the agent shell-mirror start # Access from browser # Visit: https://shellmirror.app ``` ### For Developers (Local Development) ```bash # Clone repository git clone https://github.com/karmalsky/shell-mirror.git cd terminal-mirror # Install dependencies npm install # Configure environment cp .env.example .env # Edit .env with your Google OAuth credentials # Start local WebSocket server npm start # Access at http://localhost:3000 ``` --- ## 🔐 Google OAuth Setup Shell Mirror requires Google OAuth 2.0 credentials: 1. **Google Cloud Console**: https://console.cloud.google.com/ 2. **Create OAuth Client ID**: - Application type: **Web application** - Authorized JavaScript origins: `https://shellmirror.app` - Authorized redirect URIs: `https://shellmirror.app/auth/google/callback` 3. **Copy credentials** to your `.env` file or provide during `shell-mirror setup` For detailed OAuth setup instructions, see the old README in `old_md/README_old.md` (lines 66-98). --- ## 📱 Usage ### Access Your Terminal 1. **Visit**: https://shellmirror.app 2. **Login** with Google account 3. **Dashboard** shows your connected Mac agents 4. **Connect** to start a terminal session ### Multiple Terminal Sessions - **Create new session**: Click "New Terminal Session" in dashboard - **Resume session**: Select from existing sessions list - **Switch sessions**: Use session dropdown in terminal interface - **Manage sessions**: View active sessions, close inactive ones ### Mac Agent Commands ```bash shell-mirror start # Start agent shell-mirror stop # Stop agent shell-mirror restart # Restart agent shell-mirror status # Check status shell-mirror setup # Run setup wizard ``` --- ## 🛠️ Development & Deployment ### Project Structure ``` terminal-mirror/ ├── server.js # WebSocket signaling server ├── auth.js # Google OAuth configuration ├── lib/ # CLI and agent management │ ├── auto-start.js # Mac agent auto-start logic │ ├── setup-wizard.js # Interactive setup │ └── ... ├── mac-agent/ # Mac terminal mirroring agent │ ├── agent.js # Main agent (WebRTC + sessions) │ └── http-agent.js # HTTP polling fallback ├── public/ # Frontend files │ ├── index.html # Landing page │ └── app/ # Dashboard and terminal UI ├── heroku/ # Heroku WebSocket server deployment └── php-backend/ # PHP APIs for agent registration ``` ### Deployment ```bash # Deploy WebSocket server to Heroku ./deploy-heroku.sh # Deploy website/PHP backend to TMDHosting node deploy-php.cjs # Publish NPM package (user must run manually per CLAUDE.md) ./publish.sh ``` For detailed deployment instructions, see `DEPLOYMENT-PUBLISHING-GUIDE.md`. --- ## 📊 Monitoring & Logs ### Check Status ```bash ./status.sh # Check all services ``` ### View Logs ```bash # Heroku WebSocket server heroku logs --tail -a shell-mirror # PHP backend (web) https://shellmirror.app/debug.html # Local logs tail -f server-debug.log ``` For complete operations guide, see `OPERATIONS.md`. --- ## 📚 Documentation - **README.md** (this file) - Overview and quick start - **OPERATIONS.md** - Monitoring, logs, troubleshooting - **QUICK-REFERENCE.md** - Fast command reference - **DEPLOYMENT-PUBLISHING-GUIDE.md** - Deployment procedures - **TECHNICAL-NOTES.md** - macOS firewall behavior notes - **ANALYTICS_SETUP.md** - Google Analytics and Clarity setup - **old_md/** - Archived planning documents and old README --- ## 🔍 Technical Details ### Multiple Sessions Implementation Shell Mirror supports multiple persistent terminal sessions per user: - **SessionManager class** in `mac-agent/agent.js` (line 158) - **Dashboard UI** for creating/managing sessions - **Session persistence** across browser disconnects - **Resource limits**: Max 10 sessions per agent - **Auto-cleanup**: Sessions idle > 24 hours are terminated ### WebRTC Connection - **Signaling**: Via Heroku WebSocket server - **Data Channel**: For terminal I/O (fast, low latency) - **ICE/STUN/TURN**: Automatic NAT traversal - **Fallback**: HTTP polling if WebRTC fails ### Security - **Authentication**: Google OAuth 2.0 - **Authorization**: Session-based access control - **Encryption**: WSS (WebSocket Secure) + HTTPS - **No credentials stored**: Secure token-based auth --- ## 🌐 Production URLs - **Website**: https://shellmirror.app - **WebSocket Server**: https://shell-mirror-30aa5479ceaf.herokuapp.com - **NPM Package**: https://www.npmjs.com/package/shell-mirror - **Debug Dashboard**: https://shellmirror.app/debug.html --- ## 📦 NPM Package **Current Version**: 1.5.74 ```bash # Install npm install -g shell-mirror # Usage shell-mirror --help ``` Package includes: - Mac agent with WebRTC support - Interactive setup wizard - Auto-start configuration - CLI for agent management --- ## 🐛 Troubleshooting ### Agent Not Connecting ```bash # Check agent status shell-mirror status # View logs tail -f ~/.shell-mirror/agent.log # Restart agent shell-mirror restart ``` ### WebSocket Server Issues ```bash # Check server health curl https://shell-mirror-30aa5479ceaf.herokuapp.com/health # View Heroku logs heroku logs --tail -a shell-mirror ``` ### Browser Connection Issues - **Check browser console**: F12 → Console tab - **Verify authentication**: https://shellmirror.app/api/auth/status For detailed troubleshooting, see `OPERATIONS.md`. --- ## 🤝 Contributing This is currently a personal project. For bug reports or feature requests, please check the GitHub issues. --- ## 📄 License MIT --- ## 🎯 Use Cases - **Mobile Coding**: Use Claude Code CLI or Gemini CLI from your phone - **Remote Access**: Access your development environment from anywhere - **Pair Programming**: Share terminal sessions with collaborators - **Quick Fixes**: Make quick changes on the go without VPN/SSH setup - **Multi-Device Workflow**: Seamlessly switch between devices --- *Last Updated: 2025-01-26* *Version: 1.5.74*