remug

Node.js Remote Debugger - A drop-in replacement for node that enables remote debugging via a Pinggy tunnel.

The Problem

When running Node.js applications inside Docker containers, attaching a local debugger is challenging because:

• The container's network is isolated
• Port 9229 (debugger port) isn't exposed
• Even if exposed, connecting from your local machine to a remote container requires additional setup

The Solution

remug solves this by:

1. Opening a Pinggy TCP tunnel to the debugger port (9229)
2. Running your Node.js process with --inspect-brk (pauses at startup waiting for debugger)
3. Printing connection instructions for your local machine
4. Cleaning up when the process exits

Usage

Basic Usage

Prefix node with npx remug in your command:

# Before
node index.js

# After
npx remug node index.js

In Docker

Update your Dockerfile or docker-compose.yml:

# Before
CMD ["node", "index.js"]

# After
CMD ["npx", "remug", "node", "index.js"]

Or with docker-compose:

services:
  app:
    build: .
    command: npx remug node index.js

With Arguments

All arguments are passed through to Node.js:

npx remug node --experimental-modules app.mjs
npx remug node -e "console.log('hello')"
npx remug node --max-old-space-size=4096 server.js

Output Example

When you run remug, you'll see output like:

╔════════════════════════════════════════════════════════════════╗
║                   remug, the REMote DebUGger                   ║
╚════════════════════════════════════════════════════════════════╝

[remug] Starting Pinggy tunnel to localhost:9229...
[remug] Tunnel established!

✓ Remote debugger tunnel established!

═══════════════════════════════════════════════════════════════
  CONNECT FROM YOUR LOCAL MACHINE
═══════════════════════════════════════════════════════════════

  VS Code

  Add this to your launch.json:

  {
    "type": "node",
    "request": "attach",
    "name": "Attach to Remote",
    "address": "xxx.a.pinggy.link",
    "port": xxxxx,
  }

═══════════════════════════════════════════════════════════════

The Node.js process is paused waiting for debugger to attach...
Press Ctrl+C to stop the debugger and exit.

Connecting Your Debugger

VS Code

1. Create or update .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "attach",
      "name": "Attach to Remote",
      "address": "xxx.a.pinggy.link",
      "port": xxxxx,
    }
  ]
}

2. Run the SSH tunnel command from the output
3. Press F5 or click "Run and Debug" → "Attach to Remote"

Requirements

• Node.js 18+
• Internet connection (for Pinggy tunnel)