shell-mirror

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

• Frontend (TMDHosting): Static website at https://shellmirror.app
• WebSocket Server (Heroku): Node.js signaling server for WebRTC
• PHP Backend (TMDHosting): Agent registration and authentication APIs
• Mac Agent: Local terminal mirroring agent (npm package)
• Dashboard: Real-time agent and session management interface

🚀 Quick Start

For Users (NPM Package)

# 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)

# 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:

• Google Cloud Console: https://console.cloud.google.com/
• Create OAuth Client ID:
  • Application type: Web application
  • Authorized JavaScript origins: https://shellmirror.app
  • Authorized redirect URIs: https://shellmirror.app/auth/google/callback
• 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

• Visit: https://shellmirror.app
• Login with Google account
• Dashboard shows your connected Mac agents
• 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

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

# 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

./status.sh     # Check all services

View Logs

# 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

# 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

# Check agent status
shell-mirror status

# View logs
tail -f ~/.shell-mirror/agent.log

# Restart agent
shell-mirror restart

WebSocket Server Issues

# Check server health
curl https://shell-mirror-30aa5479ceaf.herokuapp.com/health

# View Heroku logs
heroku logs --tail -a shell-mirror

Browser Connection Issues

• Debug interface: https://shellmirror.app/debug-connection.html
• 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