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

# SSH Access

> Fastest way to debug running jobs and inspect VM state

## Overview

SSH into running jobs to debug issues, inspect state, or troubleshoot your workflows in real-time. When enabled by your organization admin, access is granted to job triggerers using their GitHub SSH keys.

<Note>
  SSH access is **opt-in** and must be enabled by a GitHub organization admin from the [Settings > Features page](https://app.blacksmith.sh/settings?tab=features) before it can be used.
</Note>

## Basics

When SSH access is enabled for your organization and a job starts on a Blacksmith runner, the runner authorizes connections using the SSH keys you've added to your GitHub account.

<Warning>
  **Access requirements:**

  * SSH access must be enabled by an organization admin
  * Only the GitHub user who triggered the job can SSH into the runner
  * You must be a member of the GitHub organization
  * SSH keys must be configured in your GitHub account
</Warning>

Each runner exposes a unique SSH port that's displayed in your workflow logs at the start of every job.

### Connecting to a runner

At the beginning of each job, you'll see connection information in the `Setup runner` step:

```bash theme={"system"}
ssh -p 12345 runner@...
```

Simply copy and run the command in your terminal to connect using your GitHub SSH key.

#### Simplify connections with SSH config

Add this to your `~/.ssh/config` file to streamline connections:

```
Host *.vm.blacksmith.sh
    StrictHostKeyChecking no
    UserKnownHostsFile /dev/null
```

With this configuration, you can connect using just:

```bash theme={"system"}
ssh -p 12345 runner@...
```

<Note>
  The `StrictHostKeyChecking no` and `UserKnownHostsFile /dev/null` settings
  skip host key verification since runner VMs are ephemeral and get new host
  keys each time. This also avoids cluttering your known\_hosts file with
  temporary VM fingerprints.
</Note>

### Common use cases

#### Debug failing tests

Connect to inspect test artifacts, environment variables, or running processes when tests fail unexpectedly.

#### Verify build outputs

Check generated files, build artifacts, or compilation outputs directly on the runner.

#### Inspect environment state

Examine installed dependencies, system configurations, or runtime environments during workflow execution.

#### Troubleshoot network issues

Test connectivity, DNS resolution, or API access from within the runner environment.

## Pricing

There is no additional cost for using this feature. For all other pricing, please visit our [pricing page](https://www.blacksmith.sh/pricing).

## FAQ

<AccordionGroup>
  <Accordion title="How do I enable SSH access for my organization?">
    SSH access is opt-in and must be enabled by a GitHub organization admin:

    1. Navigate to the [Settings > Features page](https://app.blacksmith.sh/settings?tab=features)
    2. Toggle "SSH Access" to enable it for your organization
    3. Organization members can now SSH into jobs they trigger

    Only GitHub organization admins can toggle this setting.
  </Accordion>

  <Accordion title="How do I keep a job running for debugging?">
    Add a sleep step that runs on failure to give yourself time to connect and debug:

    ```yaml theme={"system"}
    - name: Keep job alive on failure for debugging
      if: failure()
      run: |
        echo "Job failed. Keeping VM alive for 30 minutes for debugging..."
        echo "SSH connection info is available in the Setup runner step above"
        sleep 1800
    ```

    <Note>
      We don't recommend using the `action-tmate` step as it's unnecessary with
      Blacksmith's built-in SSH support, and adds complexity to your workflow.
    </Note>
  </Accordion>

  <Accordion title="Why am I getting 'Could not resolve hostname'?">
    This error means the job has already finished. SSH access is only available while the job is actively running. Add a sleep step (see above) to keep the job alive longer.
  </Accordion>

  <Accordion title="Why am I getting 'Permission denied'?">
    Verify that:

    * SSH access is enabled for your organization (check with your GitHub org admin)
    * Your SSH key is properly added to your GitHub account
    * You're a member of the GitHub organization
    * You're the person who triggered the job (only the job sender can SSH in)
  </Accordion>

  <Accordion title="Can multiple people SSH into the same runner?">
    No, only the GitHub user who triggered the job can SSH into the runner.

    We're planning to add support for configuring additional SSH keys on demand through environment variables in your jobs. This will provide a secure way to grant access to team members when needed. Stay tuned for updates!
  </Accordion>

  <Accordion title="How long can I stay connected?">
    You can stay connected as long as the job is running. If you're still connected when the job completes, we provide a grace period of approximately 5 minutes before terminating the connection.
  </Accordion>

  <Accordion title="How can I get help with SSH access?">
    Let us know by opening a [support ticket](https://app.blacksmith.sh/?support=open).
  </Accordion>
</AccordionGroup>