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

# Debugging Agents with rl-cli

> Securely connect to a remote Runloop Devbox using SSH for debugging

## Overview

When working with AI-generated code, you may need to debug the state of the project after the AI has run various commands. SSH allows you to connect your computer directly to a Devbox, enabling you to debug, run remote commands, and view or modify the remote filesystem.

Runloop uses a transparent proxy to facilitate routing for all SSH access. Your SSH connection is end-to-end encrypted using standard SSH public key cryptography. The Runloop API provides a mechanism for retrieving SSH keys using a Runloop API key.

## Setup

We recommend using the Runloop CLI (`rli`) to interact with Devboxes. Install it via npm:

```bash theme={null}
npm install -g @runloop/rl-cli
```

<Info>
  For full CLI documentation including interactive mode and all available commands, see the [Runloop CLI documentation](/docs/tools/cli).
</Info>

## Create and SSH into a Devbox

<Frame>
  <img src="https://raw.githubusercontent.com/runloopai/rl-cli/main/misc/rli-ssh-demo.gif" alt="SSH into a Devbox with rli" />
</Frame>

<Steps>
  <Step title="Export your API key">
    ```bash theme={null}
    export RUNLOOP_API_KEY="ak_<your_key_here>"
    ```
  </Step>

  <Step title="Create an empty Devbox">
    ```bash theme={null}
    rli devbox create
    ```

    You'll receive the devbox ID:

    ```
    dbx_2xMEVq0JpPtxUxZikhOLm
    ```

    For full JSON output, use:

    ```bash theme={null}
    rli devbox create --output json
    ```
  </Step>

  <Step title="SSH into the Devbox">
    SSH into a running Devbox using the returned ID:

    ```bash theme={null}
    rli devbox ssh dbx_2xMEVq0JpPtxUxZikhOLm
    ```

    The CLI will wait for the devbox to be ready and then connect you to a shell:

    ```
    user@devbox-019138a2-7e80-7233-8100-1add224f41ee-zst79:~$
    ```
  </Step>

  <Step title="Exit the SSH session">
    Type `exit` to leave the SSH session.
  </Step>

  <Step title="Shut down the Devbox">
    When you're done, shut down the Devbox:

    ```bash theme={null}
    rli devbox shutdown dbx_2xMEVq0JpPtxUxZikhOLm
    ```
  </Step>
</Steps>

## Finding Devboxes with Interactive Search

The Runloop CLI includes an interactive mode that makes it easy to search and filter through your devboxes:

<Frame>
  <img src="https://raw.githubusercontent.com/runloopai/rl-cli/main/misc/rli-demo-search.gif" alt="Search devboxes with rli interactive mode" />
</Frame>

<Steps>
  <Step title="Launch interactive mode">
    ```bash theme={null}
    rli
    ```

    This opens the interactive TUI (Terminal User Interface).
  </Step>

  <Step title="Navigate to Devboxes">
    Select **Devboxes** from the main menu to view your list of devboxes.
  </Step>

  <Step title="Search for a devbox">
    Press `/` to open the search filter, then type to filter devboxes by name or ID. This is useful when you have many devboxes and need to quickly find a specific one.
  </Step>

  <Step title="Select and connect">
    Use arrow keys to navigate to the desired devbox and press `Enter` to view details or connect via SSH.
  </Step>
</Steps>

## Using VSCode with SSH

You can use SSH access to connect VSCode to the remote Devbox.

<Steps>
  <Step title="Install VSCode SSH extension">
    Install the [Visual Studio Code Remote - SSH extension](https://code.visualstudio.com/docs/remote/ssh).
  </Step>

  <Step title="Create a Devbox">
    ```bash theme={null}
    rli devbox create
    ```
  </Step>

  <Step title="Generate SSH config entry">
    ```bash theme={null}
    rli devbox ssh dbx_2xMEa8BVcYOOGtXGqWNVj --config-only
    ```
  </Step>

  <Step title="Append to SSH config file">
    ```bash theme={null}
    rli devbox ssh dbx_2xMEa8BVcYOOGtXGqWNVj --config-only >> ~/.ssh/config
    ```
  </Step>

  <Step title="Verify the configuration">
    ```bash theme={null}
    ssh dbx_2xMEa8BVcYOOGtXGqWNVj "whoami"
    ```

    This should return `user`.
  </Step>

  <Step title="Connect VSCode to your Devbox">
    You now have a ready-to-use SSH connection to the Devbox. Follow the remaining instructions in the [VSCode SSH documentation](https://code.visualstudio.com/docs/remote/ssh#_connect-to-a-remote-host) to connect VSCode to your Devbox.
  </Step>
</Steps>

## Security Notes

* All SSH connections are routed through Runloop's transparent proxy.
* Connections are end-to-end encrypted using SSH public key cryptography.
* SSH keys are generated and managed securely through the Runloop API.

By following these steps, you can securely connect to your Runloop Devbox for debugging, code inspection, and project management tasks.