Access your Mac shell from any device securely. Perfect for mobile coding with Claude Code CLI, Gemini CLI, and any shell tool.
npm install shell-mirrorAccess your Mac terminal from any device, securely. Perfect for mobile coding with Claude Code CLI, Gemini CLI, and any shell tool.
---
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.
✅ 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
---
```
┌─────────────────────────────────────────────────────────────┐
│ 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) │
└─────────────┘
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
---
`bashInstall globally
npm install -g shell-mirror
$3
`bash
Clone repository
git clone https://github.com/karmalsky/shell-mirror.git
cd terminal-mirrorInstall dependencies
npm installConfigure environment
cp .env.example .env
Edit .env with your Google OAuth credentials
Start local WebSocket server
npm startAccess 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 setupFor detailed OAuth setup instructions, see the old README in
old_md/README_old.md (lines 66-98).---
📱 Usage
$3
1. Visit: https://shellmirror.app
2. Login with Google account
3. Dashboard shows your connected Mac agents
4. Connect to start a terminal session
$3
- 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
$3
`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
$3
`
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
`$3
`bash
Deploy WebSocket server to Heroku
./deploy-heroku.shDeploy website/PHP backend to TMDHosting
node deploy-php.cjsPublish NPM package (user must run manually per CLAUDE.md)
./publish.sh
`For detailed deployment instructions, see
DEPLOYMENT-PUBLISHING-GUIDE.md.---
📊 Monitoring & Logs
$3
`bash
./status.sh # Check all services
`$3
`bash
Heroku WebSocket server
heroku logs --tail -a shell-mirrorPHP backend (web)
https://shellmirror.app/debug.htmlLocal 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
$3
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$3
- 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
$3
- 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-mirrorUsage
shell-mirror --help
`Package includes:
- Mac agent with WebRTC support
- Interactive setup wizard
- Auto-start configuration
- CLI for agent management
---
🐛 Troubleshooting
$3
`bash
Check agent status
shell-mirror statusView logs
tail -f ~/.shell-mirror/agent.logRestart agent
shell-mirror restart
`$3
`bash
Check server health
curl https://shell-mirror-30aa5479ceaf.herokuapp.com/healthView Heroku logs
heroku logs --tail -a shell-mirror
`$3
- 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`.---
This is currently a personal project. For bug reports or feature requests, please check the GitHub issues.
---
MIT
---
- 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