9remote 0.1.64 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (24) hide show
  1. package/README.md +179 -62
  2. package/cli/index.js +701 -293
  3. package/cli/utils/assets/trayIcon.ico +0 -0
  4. package/cli/utils/cloudflared.js +72 -36
  5. package/cli/utils/permissions.js +5 -5
  6. package/cli/utils/pids.js +114 -0
  7. package/cli/utils/token.js +3 -1
  8. package/cli/utils/tray.js +251 -0
  9. package/cli/utils/tui.js +209 -34
  10. package/cli/utils/updateChecker.js +107 -13
  11. package/dist/assets/trayIcon.ico +0 -0
  12. package/dist/cli.cjs +1 -36
  13. package/dist/ptyDaemon.cjs +1 -10
  14. package/dist/server.cjs +2 -184
  15. package/dist/ui/assets/{index-BfTPkO8b.css → index-COWVKicT.css} +1 -1
  16. package/dist/ui/assets/index-njTKNAa6.js +8 -0
  17. package/dist/ui/index.html +2 -2
  18. package/index.js +174 -618
  19. package/lib/constants.js +64 -0
  20. package/lib/deviceApproval.js +116 -0
  21. package/lib/router.js +134 -0
  22. package/lib/socketio.js +168 -25
  23. package/package.json +6 -1
  24. package/dist/ui/assets/index-B37vtDoz.js +0 -8
package/README.md CHANGED
@@ -1,119 +1,236 @@
1
1
  <div align="center">
2
+ <img src="https://raw.githubusercontent.com/decolua/9remote/main/images/9remote.png" alt="9Remote" width="800"/>
2
3
 
3
- # 9remote
4
+ # 9Remote — Terminal in Your Pocket
4
5
 
5
- **Your Mac/Linux terminal in your pocket — anywhere, instantly**
6
+ **Your Mac/Linux/Windows terminal, remote desktop, and file explorer — accessible from any phone or browser, anywhere, instantly.**
6
7
 
7
- [![npm version](https://img.shields.io/npm/v/9remote)](https://www.npmjs.com/package/9remote)
8
- [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
9
- [![npm downloads](https://img.shields.io/npm/dm/9remote)](https://www.npmjs.com/package/9remote)
10
-
11
- [🌐 Web App](https://9remote.cc) • [📖 Docs](https://docs.9remote.cc) • [🚀 Get Started](#-quick-start)
8
+ [![npm version](https://img.shields.io/npm/v/9remote.svg)](https://www.npmjs.com/package/9remote)
9
+ [![Downloads](https://img.shields.io/npm/dm/9remote.svg)](https://www.npmjs.com/package/9remote)
10
+ [![License](https://img.shields.io/badge/license-MIT-blue.svg)](#-license)
12
11
 
12
+ [🚀 Quick Start](#-quick-start) • [💡 Features](#-features) • [🌐 Website](https://9remote.cc) • [📖 Docs](https://docs.9remote.cc)
13
13
  </div>
14
14
 
15
15
  ---
16
16
 
17
- ## Why 9remote?
17
+ ## 🤔 Why 9Remote?
18
+
19
+ **Remote access today is painful:**
20
+
21
+ - ❌ **SSH** — firewall rules, port forwarding, SSH keys
22
+ - ❌ **VPN** — overkill just to check a terminal
23
+ - ❌ **ngrok / tunnels** — expire, lose connection
24
+ - ❌ **TeamViewer** — slow, desktop-only, paid
25
+ - ❌ **Termius** — SSH-only, no desktop, no browser
18
26
 
19
- - ❌ **SSH is a hassle** — need to open firewall, configure port forwarding, manage keys
20
- - ❌ **VPN is overkill** — too complex to set up just to check a terminal
21
- - ❌ **ngrok / tunnels expire** — lose connection, have to restart everything
27
+ **9Remote solves all of it:**
22
28
 
23
- **9remote solves it:**
24
- - ✅ **One command** — `npx 9remote`, scan QR, done
25
- - ✅ **Auto tunnel** — Cloudflare tunnel starts automatically, no port forwarding
26
- - ✅ **Works on phone** — full terminal from your browser, under 50ms latency
27
- - ✅ **Remote Desktop** — view and control your screen, mouse & keyboard
28
- - ✅ **Persistent sessions** — PTY daemon survives server restarts
29
+ - ✅ **One command** — install, scan QR, done in 30 seconds
30
+ - ✅ **Auto tunnel** — Cloudflare tunnel, no port forwarding
31
+ - ✅ **All-in-one** — terminal + desktop + file explorer + editor
32
+ - ✅ **Works on phone** — full workspace from browser, <50ms latency
33
+ - ✅ **Persistent** — PTY sessions survive restarts
34
+ - ✅ **Pair Device** — only approved devices connect, zero signup
29
35
 
30
36
  ---
31
37
 
32
38
  ## ⚡ Quick Start
33
39
 
34
40
  ```bash
35
- npx 9remote
41
+ npm install -g 9remote
42
+ 9remote
36
43
  ```
37
44
 
38
- Scan the QR code on your phone → you're in.
45
+ 🎉 **Scan the QR → pair your device → you're in.**
39
46
 
40
- Or install globally:
47
+ > Works on **macOS, Linux, Windows**. Requires Node.js 20+.
41
48
 
42
- ```bash
43
- npm install -g 9remote
44
- 9remote
45
- ```
49
+ ### CLI Commands
46
50
 
47
- > **Ready in 30 seconds. No config needed.**
51
+ | Command | Description |
52
+ |---------|-------------|
53
+ | `9remote` | TUI mode — interactive menu with QR code |
54
+ | `9remote ui` | Web UI mode — opens dashboard at `localhost:2208` |
48
55
 
49
56
  ---
50
57
 
51
58
  ## ✨ Features
52
59
 
53
- - 🖥️ **Remote Terminal** — Full PTY shell, always on, persistent across reconnects
54
- - 🖱️ **Remote Desktop** — Live screen streaming via WebRTC + mouse/keyboard control
55
- - 📁 **File Explorer** — Browse, upload, download files from your browser
56
- - 📱 **QR Login** — One-time key (30 min) for quick mobile access
57
- - 🔒 **E2E Secure** — All traffic through Cloudflare tunnel, no open ports
58
- - 🔄 **Auto Restart** — Server + tunnel auto-recover on crash
60
+ | Feature | What It Does |
61
+ |---------|--------------|
62
+ | 🖥️ **Remote Terminal** | Full PTY shell via WebSocket |
63
+ | 🖱️ **Remote Desktop** | Live screen streaming via WebRTC |
64
+ | 📁 **File Explorer** | Browse, upload, download files |
65
+ | 💻 **Code Editor** | Built-in editor with syntax highlighting |
66
+ | 🔗 **Git Integration** | Run git commands with visual status |
67
+ | 📱 **Mobile Optimized** | Touch-friendly UI, gesture controls |
68
+ | 🔑 **QR Login** | One-time 30-min key, scan to connect |
69
+ | 🔒 **Auto Tunnel** | Cloudflare tunnel, no port forwarding |
70
+ | 🔄 **Persistent Sessions** | PTY daemon survives restarts |
71
+ | 🌍 **Multi-Device Sync** | Same session across phone/tablet/laptop |
72
+ | 🔔 **Push Notifications** | Build finished? Get notified |
73
+ | 🤖 **AI Integration** | Claude Code, Codex, Cursor, OpenClaw |
74
+ | 🌐 **Local Sites Proxy** | Expose `localhost:3000` to phone |
75
+ | 🔐 **Pair Device** | Approve each device before it connects |
76
+ | 🆓 **No Account** | Machine ID + QR key, zero signup |
59
77
 
60
78
  ---
61
79
 
62
- ## 📖 CLI Commands
80
+ ## 🎯 Use Cases
63
81
 
64
- | Command | Description |
65
- |---|---|
66
- | `9remote` | TUI mode — interactive menu with QR |
67
- | `9remote ui` | Web UI mode — open browser dashboard |
68
- | `9remote start` | Auto start server + tunnel (headless) |
82
+ **Code from bed** — 11 PM, bug in prod, laptop in another room? Open the app on your phone, scan QR, fix, push, sleep.
83
+
84
+ **Fix bugs at a cafe** — Production down, only phone + café Wi-Fi? Connect to your home Mac, tail logs, edit config, deploy.
85
+
86
+ **Deploy on vacation** — Client needs a hotfix, you're on the beach? Phone → 9remote → git pull → deploy → back to the beach.
87
+
88
+ **On-call engineer** — 3 AM alert, don't want to boot laptop? Push notification → terminal + remote desktop from bed.
69
89
 
70
90
  ---
71
91
 
92
+ ## 📖 Setup
93
+
94
+ <details>
95
+ <summary><b>🔑 First Run & QR Login</b></summary>
96
+
97
+ On first run, 9Remote generates two keys:
98
+
99
+ - **Permanent Key** — stored locally, tied to your machine ID
100
+ - **One-Time Key** — 30-minute temporary key for the QR code
101
+
102
+ **Connect from phone:**
103
+ 1. Run `9remote` on your machine
104
+ 2. A QR code appears in the terminal
105
+ 3. Open [9remote.cc](https://9remote.cc) on your phone (or the mobile app)
106
+ 4. Scan the QR → connected instantly
107
+
108
+ > Keys are **never** stored on our servers after the session ends.
109
+
110
+ </details>
111
+
72
112
  <details>
73
- <summary><b>🔧 How it works</b></summary>
113
+ <summary><b>🖱️ Remote Desktop (macOS)</b></summary>
114
+
115
+ Requires two system permissions:
116
+
117
+ 1. **Screen Recording** — `System Settings → Privacy & Security → Screen Recording`
118
+ 2. **Accessibility** — `System Settings → Privacy & Security → Accessibility`
119
+
120
+ Enable Terminal (or the app you ran `9remote` from), then toggle Remote Desktop in the TUI menu.
74
121
 
75
- 1. **Start** — `9remote` spawns a local server on port `2208`
76
- 2. **Tunnel** — A Cloudflare Quick Tunnel is created automatically (no account needed)
77
- 3. **QR** — A one-time login link is generated and shown as QR code
78
- 4. **Connect** — Scan from your phone → authenticated session via [9remote.cc](https://9remote.cc)
79
- 5. **Transport** — Terminal uses WebSocket; Remote Desktop uses WebRTC DataChannel for low latency
122
+ **Performance:**
123
+ - Adaptive framerate: 60ms active / 400ms idle
124
+ - Tile-based diff rendering (only changed regions sent)
125
+ - WebRTC DataChannel for minimal latency
80
126
 
81
127
  </details>
82
128
 
83
129
  <details>
84
- <summary><b>📡 Remote Desktop</b></summary>
130
+ <summary><b>🌐 Local Sites Proxy</b></summary>
85
131
 
86
- - Screen streaming via WebRTC (adaptive: 60ms active / 400ms idle)
87
- - Tile-based diff rendering — only changed regions are sent
88
- - Mouse & keyboard control via `robotjs`
89
- - Requires macOS permissions: **Screen Recording** + **Accessibility**
132
+ Expose your local dev servers automatically:
90
133
 
91
- Enable from TUI menu: `Remote Desktop → Toggle ON`
134
+ ```
135
+ http://localhost:3000 → https://<tunnel>/proxy/3000/
136
+ http://localhost:5173 → https://<tunnel>/proxy/5173/
137
+ ```
138
+
139
+ Perfect for testing responsive design on real devices, sharing WIP builds, or mobile debugging without USB.
92
140
 
93
141
  </details>
94
142
 
143
+ ---
144
+
145
+ ## ❓ FAQ
146
+
95
147
  <details>
96
- <summary><b>🔑 Keys & Security</b></summary>
148
+ <summary><b>🔒 Is it secure?</b></summary>
97
149
 
98
- - **Permanent Key** — stored locally, tied to your machine ID
99
- - **One-Time Key** — 30-minute temporary key for quick phone access
100
- - Keys are never stored on our servers after session ends
101
- - Regenerate your key anytime from the TUI menu
150
+ **Yes.** Every new device must be explicitly approved via **Pair Device** before it can access the host. Plus:
151
+ - No open ports — Cloudflare tunnel is outbound-only
152
+ - Keys never stored on our servers after session ends
153
+ - No terminal output, files, or screen data collected
154
+ - One-time QR keys expire in 30 minutes
155
+
156
+ </details>
157
+
158
+ <details>
159
+ <summary><b>💰 Is it free?</b></summary>
160
+
161
+ **Yes.** Free to use, no signup, no credit card. MIT licensed.
162
+
163
+ </details>
164
+
165
+ <details>
166
+ <summary><b>🌐 Do I need to open ports?</b></summary>
167
+
168
+ **No.** Uses Cloudflare Quick Tunnel — outbound only. Works behind home NAT, corporate firewalls, mobile hotspots, VPNs.
169
+
170
+ </details>
171
+
172
+ <details>
173
+ <summary><b>📴 Does it work on LAN only?</b></summary>
174
+
175
+ **Yes.** A **LocalFirstAdapter** races LAN vs tunnel and uses whichever is faster. If phone and host share the same Wi-Fi, traffic stays local.
176
+
177
+ </details>
178
+
179
+ <details>
180
+ <summary><b>🤖 Can I use AI coding tools through 9Remote?</b></summary>
181
+
182
+ **Yes.** Works seamlessly with Claude Code, OpenAI Codex CLI, Cursor, OpenClaw, and any CLI tool. Run them on your host, access from your phone.
102
183
 
103
184
  </details>
104
185
 
186
+ <details>
187
+ <summary><b>🖥️ What platforms are supported?</b></summary>
188
+
189
+ **Host:** macOS (Intel + Apple Silicon), Linux (x64, arm64), Windows (x64)
190
+ **Client:** Any modern browser, iOS 14+, Android 8+
191
+
192
+ </details>
193
+
194
+ ---
195
+
196
+ ## 🐛 Troubleshooting
197
+
198
+ **"Port 2208 already in use"**
199
+ - Another instance running → `pkill -f 9remote` and retry
200
+ - Or use a different port: `PORT=3308 9remote`
201
+
202
+ **"Cloudflare tunnel failed to start"**
203
+ - Check internet connection
204
+ - `cloudflared` auto-installed on first run; otherwise install manually from [cloudflared docs](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/)
205
+
206
+ **"Screen Recording / Accessibility denied" (macOS)**
207
+ - Grant permissions in `System Settings → Privacy & Security`, then restart 9Remote
208
+
209
+ **"QR code expired"**
210
+ - Keys expire in 30 minutes → regenerate from TUI menu: `Key → Regenerate`
211
+
212
+ **"Can't connect from phone"**
213
+ - Check both devices have internet
214
+ - Try forcing tunnel mode: Settings → Connection → Tunnel only
215
+
105
216
  ---
106
217
 
107
- ## 🛠️ Built With
218
+ ## 📧 Links
108
219
 
109
- - [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) — Zero-config secure tunnel
110
- - [node-datachannel](https://github.com/murat-dogan/node-datachannel) — WebRTC for low-latency desktop streaming
111
- - [node-pty](https://github.com/microsoft/node-pty) — Persistent PTY terminal sessions
112
- - [Socket.IO](https://socket.io/) — Real-time terminal + signaling
113
- - [Preact](https://preactjs.com/) — Lightweight Web UI
220
+ - **Website:** [9remote.cc](https://9remote.cc)
221
+ - **Docs:** [docs.9remote.cc](https://docs.9remote.cc)
222
+ - **GitHub:** [github.com/decolua/9remote](https://github.com/decolua/9remote)
223
+ - **Issues:** [github.com/decolua/9remote/issues](https://github.com/decolua/9remote/issues)
224
+ - **Community:** [facebook.com/groups/9teamvn](https://www.facebook.com/groups/9teamvn)
114
225
 
115
226
  ---
116
227
 
117
- ## 📝 License
228
+ ## 📄 License
229
+
230
+ MIT © 9Team
118
231
 
119
- MIT © [9remote](https://github.com/decolua/9remote)
232
+ ---
233
+
234
+ <div align="center">
235
+ <sub>Built with ❤️ for developers who code from anywhere — bed, beach, or bus.</sub>
236
+ </div>