Remote debugging

You can open remote consoles to running tasks by pausing at breakpoints or running rwx ssh.

Debugging at breakpoints

To set a breakpoint, run rwx-breakpoint anywhere in your task. It's a binary, so you can run it directly from your run script or from inside another bash script.

Flags

rwx-breakpoint supports the following flags:

Timeouts are specified as durations like 5m or 1h.

When RWX encounters a breakpoint, it will pause execution and make a private SSH connection available to the running task.

tasks:
  - key: demo-breakpoint
    run: |
      echo "hello world" | tee greeting.txt
      rwx-breakpoint
    env:
      SOME_ENV: the value

To name a debugging session and customize its timeouts:

tasks:
  - key: long-debug-session
    run: |
      rwx-breakpoint --name=investigate-timeout --attachment-timeout=1h --session-timeout=2h

Once the breakpoint has been hit, use the rwx debug command in the RWX CLI to open a shell.

The UI will show the command to run. It'll look like this:

rwx debug c2ba55ecd392583f4446323156d0e8bd

Multiple breakpoint sessions

Every invocation of rwx-breakpoint creates an independent debugging session, so a task can have several sessions open at the same time.

Give each session a distinct name to make it easier to find. If one session is ready, rwx debug connects to it. If several sessions are ready in an interactive terminal, the CLI lists the available session names and IDs to choose from.

To select a session directly, pass its ID or unique open name with --session:

rwx debug --session investigate-timeout c2ba55ecd392583f4446323156d0e8bd

RWX uses dtach to drop you into a bash shell in the context which the breakpoint was set.

In the above task definition, you can echo $SOME_ENV and cat greeting.txt

When you're done debugging, run exit or press ctrl+d to end your session.

You'll see output in your task logs in the UI indicating that your debugging session has finished.

Connecting with rwx ssh

To open a console without adding a breakpoint, run rwx ssh with a task ID:

rwx ssh c2ba55ecd392583f4446323156d0e8bd

rwx ssh opens an interactive SSH session while the task continues to run.

Use --name to identify the session. Names must be unique among the task's open debugging sessions.

rwx ssh --name investigate-timeout c2ba55ecd392583f4446323156d0e8bd

See the rwx ssh CLI reference for all options.