CursorRemote

Remote control for your local Cursor AI agent — monitor sessions, approve steps, and send tasks from your phone, tablet, or another computer's browser, or via Telegram, while Cursor runs on your machine.

Features

• Mobile Web Client -- real-time chat view with Cursor's dark theme, approve/reject buttons, plan widgets, run command cards, mode/model switching
• Telegram Integration -- auto-sync conversations into forum topics, approve via inline buttons, send prompts from any device
• Multi-Window Monitoring -- all Cursor windows polled in parallel via separate CDP connections (no UI switching)
• Auto-Topic Creation -- new chat tabs automatically get a Telegram topic created
• VS Code Extension -- integrated sidebar with server status, start/stop controls, setup wizard, and settings
• Persistent State -- messages, topics, sync, and auth all survive server restarts

How It Works

┌─────────────────────────────────────────────────────────────────┐
│  Cursor Extension (optional)                                    │
│  Spawns server, provides UI, manages lifecycle                  │
│                                                                 │
│  Cursor IDE  ──CDP──>  Relay Server  ──socket.io──>  Browser    │
│  (Windows/Mac)          (Node.js)     ──Bot API───>  Telegram   │
└─────────────────────────────────────────────────────────────────┘

1. Cursor IDE runs with Chrome DevTools Protocol enabled (--remote-debugging-port=9222)
2. Relay Server connects via CDP, extracts agent chat state from the DOM
3. Window Monitor polls all windows in parallel using separate CDP connections
4. Browser Client displays the conversation in real time on any device
5. Telegram Bot (optional) mirrors data into auto-created forum topics

Which Setup Should I Use?

Setup A: Extension (Recommended)

1. Install the Extension

Download the latest .vsix from releases, then install:

# From the command line
code --install-extension cursor-remote-X.Y.Z.vsix

Or in Cursor: open the Command Palette (Ctrl+Shift+P), run Extensions: Install from VSIX..., and select the file.

2. Enter Your License Key

Open the CursorRemote panel in the activity bar (left sidebar). You'll see a "License Key Required" prompt — click it to enter your key. It's stored securely in the OS credential store via VS Code's Secrets API.

Don't have a key? Get one from the store.

3. Launch Cursor with CDP Enabled

Add --remote-debugging-port=9222 to your Cursor shortcut, or run:

# Windows
& "$env:LOCALAPPDATA\Programs\cursor\Cursor.exe" --remote-debugging-port=9222

# macOS
open -a Cursor --args --remote-debugging-port=9222

# Linux
cursor --remote-debugging-port=9222

Important: Fully quit and restart Cursor after adding the flag. On macOS use Cmd+Q (not just close the window). Verify: http://localhost:9222/json should return JSON.

4. Server Auto-Starts

The extension automatically starts the relay server when Cursor launches. Check the CursorRemote sidebar panel for live status:

• Server status -- Running / Stopped / Disconnected
• CDP connection -- Connected / Disconnected with active workspace name
• Agent status -- idle, running tool, etc. with current mode and model
• Connected clients -- number of browser sessions
• Start / Stop buttons -- control the server directly from the sidebar

If it doesn't auto-start, click Start Server in the sidebar or run CursorRemote: Start Server from the Command Palette.

5. Configure Networking and Connect

Run CursorRemote: Open Setup Panel (or click Open Setup Panel in the sidebar) to configure:

• Networking -- choose Localhost (default), LAN (all interfaces), or a specific IP (Tailscale)
• Web Client Password -- auto-generated on first install; copy it or set your own
• Telegram -- step-by-step wizard with bot token entry, registration token display, and user status

Open http://<server-ip>:<port> in any browser on your phone, tablet, or another computer and enter the password.

Multi-window: Only one server instance runs across all Cursor windows. The first window to start becomes the owner; other windows attach as observers and auto-recover if the owner closes.

Extension Commands

Extension Settings

All settings are under cursorRemote.* in VS Code Settings. Each setting includes inline documentation with links to relevant guides.

Setup B: Standalone Server (Without Extension)

Run the relay server directly from the command line — useful for headless machines, remote servers, or if you prefer managing configuration via .env files.

Prerequisites

• Node.js 20+
• Cursor IDE with --remote-debugging-port=9222
• A browser on the same network (for the web client)

Install and Run

git clone https://github.com/len5ky/CursorRemote.git cursor-ide-remote
cd cursor-ide-remote
npm install
cp .env.example .env
npm run dev

On first run, you'll be prompted for a license key. Get one from the store. The key is saved to data/license.key.

Edit .env to configure the server. For Telegram, set TELEGRAM_ENABLED=true and TELEGRAM_BOT_TOKEN.

Standalone Configuration

Production

npm run build
npm start

Ensure data/license.key exists before running npm start (no interactive prompt in production mode).

WSL2 users: see Setup Guide for port forwarding details.

Security

CursorRemote ships with secure defaults out of the box:

• Localhost-only -- the server binds to 127.0.0.1 by default, so it's never exposed to the network until you explicitly choose to.
• Auto-generated password (extension) -- a cryptographically random password is created on first install and used to protect the web client.
• Encrypted key storage (extension) -- your license key and password are stored in the OS credential store via VS Code's Secrets API.

Accessing from another device

Option A: Tailscale (recommended) -- install Tailscale on your computer and phone. Your server is accessible over a private WireGuard mesh with no port forwarding needed. See the Tailscale setup guide.

Option B: LAN access -- open the Setup Panel (extension) or set SERVER_HOST=0.0.0.0 (standalone). The server binds to all interfaces and requires a password.

Both options can be combined for defense in depth.

Privacy

CursorRemote is 100% self-hosted. There is no phone-home, no telemetry, no analytics, no usage tracking. The software never connects to our servers — not at startup, not during use, not ever. License validation happens entirely offline against your local key. Your code, your conversations, and your agent activity stay on your machine and your network. We don't see any of it.

Telegram Setup

The easiest way to set up Telegram is via the Setup Panel — run CursorRemote: Open Setup Panel and switch to the Telegram tab for a step-by-step wizard that shows your registration token and registered users.

Manual Setup

1. Create a bot: Message @BotFather > /newbot > copy the token
2. Configure: Set cursorRemote.telegram.botToken in VS Code Settings (extension) or TELEGRAM_BOT_TOKEN in .env (standalone), and enable Telegram
3. Create a group: Create a Telegram supergroup with Topics enabled, add bot as admin with Manage Topics permission
4. Register: Start the server, check the Output panel (extension) or terminal (standalone) for the registration token, send /register <token> in the group
5. Sync: Send /sync to enable auto-sync. Topics are auto-created for each window + chat tab.

Bot Commands

Plain text in any topic is sent as a prompt to the mapped Cursor agent.

Scripts

Documentation

• Setup Guide -- installation, networking, Telegram, troubleshooting
• Tailscale Setup -- secure remote access without exposing to the internet
• Product Requirements -- features, state model, protocol
• Architecture -- components, data flow, decisions
• Telegram PRD -- message formats, commands
• Telegram Architecture -- multi-window, queues, lifecycle
• Extension PRD -- VS Code extension features, settings, build