🐛 sandbox-debugger 🐛

Debug a Node.js process anywhere using chrome://inspect or node-inspect

node debug port 9229	⟷	sandbox debug client	⟷	sandbox debug broker

Interactive debugging using inspect, debug the same way you do with a local process.

Supports a Node.js process running

• on a machine you can't ssh / don't have access to
• in a Docker Container with no exposed ports
• on Travis CI
• on Github Actions
• on Bitbucket Pipelines
• on GitLab CI/CD
• on AWS CodeBuild
• on AWS Lambda
• on Heroku
• on Runkit
• anywhere that allows outbound internet traffic to port 80

How it works?

Node opens a websocket when in debug mode, both the sandbox server and client work by piping the websocket data via the broker.

Run sandbox server

The server is used as a gatekeeper for the debug messages.

1npx sandbox-debugger-server

or

1ᐅ docker run \
2  --name sandbox-debugger \
3  -ti \
4  --rm \
5  -p 9229:9229 \
6  jameskyburz/sandbox-debugger

The server will output

1   Debug server started!                       
2                                               
3    - To debug a new process:                  
4      export DEBUG_PROXY=xxx.xxx.x.xxx:9229    
5      node index.js                            
6
7    - To debug an existing process:            
8      export DEBUG_PROXY=xxx.xxx.x.xxx:9229    
9      export DEBUG_PID=<pid of node process>   
10      npx sandbox-debugger                     
11
12    - Find pid of first running Node.js process
13      ps ax |
14      grep 'no[d]e ' |
15      awk '{print $1}' |
16      head -n 1
17
18    - Allow remote access to me:              
19      npx ngrok http 9229 --scheme http

Create a tunnel to our sandbox server process

Using ngrok you can tunnel to the locally running broker from for example aws lambda.

1npx ngrok http 9229 --scheme http

Client

Example debug current process

1// index.js
2require('sandbox-debugger')
3debugger
4console.log('all done')

1# DEBUG_PROXY is ip:port to sandbox broker
2DEBUG_PROXY=ip:port node index.js

Example debug an already running process

1# DEBUG_PROXY is ip:port to sandbox broker
2# DEBUG_PID is pid of process to debug
3DEBUG_PROXY=ip:port DEBUG_PID=x npx sandbox-debugger

AWS Lambda

Environment variable DEBUG_PROXY needs to point to the ngrok address including the port part :80.

The easiest way to debug lambda is to edit the code in aws console.

Copy the contents of https://unpkg.com/sandbox-debugger@latest/dist/index.js to debug.js, and require('./debug.cjs') instead of sandbox-debugger

ESM example

1  import { createRequire } from 'node:module'
2  const require = createRequire(import.meta.url)
3  require('./debug.cjs')

license

Apache License, Version 2.0