> ## Documentation Index
> Fetch the complete documentation index at: https://namespace.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Interactive Access

export const CenteredImage = ({src, alt, width, caption, className}) => {
  const [basePath, setBasePath] = useState("");
  useEffect(() => {
    const path = window.location.pathname;
    setBasePath(path === "/docs" || path.startsWith("/docs/") ? "/docs" : "");
  }, []);
  return <Frame caption={caption} className={className} style={{
    maxWidth: width,
    marginInline: "auto"
  }}>
			<OptimizedImage src={`${basePath}${src}`} alt={alt} />
		</Frame>;
};

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](https://cloud.namespace.so/workspace/ghrunners).
If the job is currently running you will see the step the is currently runing.

<CenteredImage width={600} alt="job page, current step troubleshooting" src="/docs/images/github-actions/job-troubleshoot-row.webp" />

Press the Troubleshoot button and a terminal session into the execution environment
of the current step will open:

<CenteredImage width={600} alt="job troubleshoot page" src="/docs/images/github-actions/job-troubleshoot-page.webp" />

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.

<h2 id="setting-breakpoints">
  Setting breakpoints
</h2>

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.

```yaml {17-21} theme={null}
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`](/docs/reference/github-actions/breakpoint) will emit instructions how to access the paused runner.
The action is compatible with any runners and also available outside of Namespace.

```bash theme={null}
▶ 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](/docs/solutions/github-actions/debugging/remote-display#vnc-remote-display) into the runner to examine the environment, run commands manually, and understand exactly what is happening in your workflow.

<Info>
  Workflows with active breakpoint sessions are still "running" and continue to count towards your usage.
</Info>

## 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.

<CenteredImage width={600} alt="Runner Terminal access" src="/docs/images/github-actions/runnerterminal.webp" />

Alternatively, you can jump into an SSH session from your command line.

<Steps titleSize="h3">
  <Step id="identify-the-runner-instance-id" title={<span>Identify the runner instance id</span>}>
    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](https://cloud.namespace.so/workspace/actions/repos).
  </Step>

  <Step id="connect-to-the-runner" title={<span>Connect to the runner</span>}>
    Open an SSH session:

    <Tabs>
      <Tab title="nsc CLI">
        Connect with [Namespace CLI](/docs/reference/cli/installation):

        ```bash theme={null}
        nsc ssh <instance-id>
        ```
      </Tab>

      <Tab title="Native SSH">
        Connect with native SSH:

        ```bash theme={null}
        ssh <instance-id>@ssh.<region>.namespace.so
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

**Note:** Native SSH access is not enabled by default. Reach out to our [support team](mailto:support@namespace.so) to get enrolled.

## Next steps

* [Debugging overview](/docs/solutions/github-actions/debugging)
* [Remote Display](/docs/solutions/github-actions/debugging/remote-display)