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.

$3

✅ 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) │
└─────────────┘
`

$3

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

$3

`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

`

$3

`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

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

$3


`bash
./status.sh # Check all services
`

$3

`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

$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-mirror

Usage

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 status

View logs

tail -f ~/.shell-mirror/agent.log

Restart agent

shell-mirror restart
`

$3

`bash


Check server health

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

View 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`.

---

🤝 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