Interactive Access

Get direct access to your runners while they’re executing your workflows, enabling real-time debugging and investigation.

Pause job execution

You can pause execution of a running job and connect to it using an interactive terminal for command-line debugging and investigation. This is perfect for examining file systems, running diagnostic commands, and troubleshooting build environments. Find the target job on Namespace dashboard. If the job is currently running you will see the step the is currently runing. Press the Troubleshoot button and a terminal session into the execution environment of the current step will open: The execution of the current step will continue, but the workflow will not proceed to the next step until you finish the troubleshooting session and press Resume. If step execution is paused but no troubleshooting session is open, execution will automatically resume after 10 minutes of inactivity.

Setting breakpoints

Pause your GitHub Actions workflows at any point to investigate the current state, examine variables, and debug issues interactively. Using breakpoints eliminates the need to replicate the CI environment locally. You can just jump into the failed state and start exploring immediately.

jobs:
  tests:
    runs-on: namespace-profile-default
    permissions:
      id-token: write
      contents: read

    steps:
      - name: Checkout the repository
        uses: actions/checkout@v4

      - name: Run tests
        shell: bash
        run: ...

      - name: Breakpoint if tests failed
        if: failure()
        uses: namespacelabs/breakpoint-action@v0
        with:
          duration: 15m
          authorized-users: <your-github-username>,<another-github-username>

The breakpoint-action will emit instructions how to access the paused runner. The action is compatible with any runners and also available outside of Namespace.

▶ Run namespacelabs/breakpoint-action@v0
Connecting endpoint=rendezvous.namespace.so:5000
┌──────────────────────────────────────────────────────────────────────┐
│ Breakpoint! Running until Jun 26 09:58:26 UTC (14 minutes from now). │
└──────────────────────────────────────────────────────────────────────┘
Connect with:
ssh -p 44793 runner@rendezvous.namespace.so

While the breakpoint is active, you can also VNC into the runner to examine the environment, run commands manually, and understand exactly what is happening in your workflow.

Workflows with active breakpoint sessions are still “running” and continue to count towards your usage.

Instance SSH access

If the above methods are not available you can access the instance that is executing the job directly without pausing the workflow. The simplest path to jump into an interactive terminal is through your browser with our web SSH interface. Alternatively, you can jump into an SSH session from your command line.

Identify the runner instance id

Open the Set up job step in your job logs. The instance id can be found in the runner name.Runner name: 'nsc-runner-<instance-id>'You can also look up which instance ran which job in our dashboard.

Connect to the runner

Open an SSH session:

nsc CLI
Native SSH

Connect with Namespace CLI:

nsc ssh <instance-id>

Connect with native SSH:

ssh <instance-id>@ssh.<region>.namespace.so

Note: Native SSH access is not enabled by default. Reach out to our support team to get enrolled.

Products

Platform

Administration

Pause job execution

Setting breakpoints

Instance SSH access

Identify the runner instance id

Connect to the runner

Next steps

​Pause job execution

​Setting breakpoints

​Instance SSH access

Identify the runner instance id

Connect to the runner

​Next steps

Pause job execution

Setting breakpoints

Instance SSH access

Next steps