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

# Local Tunnel

> Run Decipher tests against your local development environment using a secure tunnel

The Decipher Tunnel CLI exposes your local development server to the internet through a secure tunnel, giving Decipher's test runner a public URL to reach your app. This lets you record and run tests against localhost without deploying — powered by ngrok under the hood.

<Info>
  **Prerequisites:**

  * Node.js 18 or later
  * A [Decipher account](https://app.getdecipher.com)
  * A local dev server running on a known port (e.g., `localhost:3000`)
</Info>

## Step 1: Install the CLI

Install the tunnel CLI globally using your preferred package manager:

<CodeGroup>
  ```bash npm theme={null}
  npm install -g @decipher-sdk/decipher-tunnel
  ```

  ```bash yarn theme={null}
  yarn global add @decipher-sdk/decipher-tunnel
  ```

  ```bash pnpm theme={null}
  pnpm add -g @decipher-sdk/decipher-tunnel
  ```

  ```bash bun theme={null}
  bun add -g @decipher-sdk/decipher-tunnel
  ```
</CodeGroup>

## Step 2: Authenticate

<Steps>
  <Step title="Start the login flow">
    Run the login command in your terminal:

    ```bash theme={null}
    decipher-tunnel login
    ```

    Your browser will open to the Decipher dashboard.
  </Step>

  <Step title="Copy your token">
    The dashboard displays a one-time authentication token. Click the copy button to copy it to your clipboard.
  </Step>

  <Step title="Paste the token">
    Switch back to your terminal and paste the token when prompted. You'll see a success message confirming you're logged in.
  </Step>
</Steps>

## Step 3: Start a Tunnel

<Steps>
  <Step title="Start your local dev server">
    Make sure your app is running locally. For example:

    ```bash theme={null}
    npm run dev
    ```

    Confirm it's accessible at `http://localhost:3000` (or whichever port you use).
  </Step>

  <Step title="Open the tunnel">
    In a separate terminal window, run:

    ```bash theme={null}
    decipher-tunnel forward -p 3000
    ```

    Replace `3000` with your local server's port. The CLI will start the tunnel and display your public URL:

    ```
    https://{userId}.tunnel.getdecipher.com
    ```

    Incoming requests are logged in real-time so you can see test traffic as it arrives.
  </Step>

  <Step title="Stop the tunnel">
    Press **Ctrl+C** in the terminal to stop the tunnel, or run:

    ```bash theme={null}
    decipher-tunnel kill
    ```
  </Step>
</Steps>

## Step 4: Use the Tunnel URL in Decipher

Once your tunnel is running, use the public URL as the **Base URL** when recording or running tests in the Decipher dashboard. Any test pointed at that URL will hit your local server through the tunnel.

<Tip>
  Your tunnel URL is stable — it stays the same every time you run `decipher-tunnel forward`, so you don't need to update your tests each session.
</Tip>

## CLI Reference

| Command                             | Description                            |
| ----------------------------------- | -------------------------------------- |
| `decipher-tunnel login`             | Authenticate with Decipher             |
| `decipher-tunnel logout`            | Revoke stored credentials              |
| `decipher-tunnel forward -p <port>` | Start a tunnel to the given local port |
| `decipher-tunnel me`                | Show the currently authenticated user  |
| `decipher-tunnel list`              | Show the active tunnel                 |
| `decipher-tunnel kill`              | Stop the active tunnel                 |

## Troubleshooting

<AccordionGroup>
  <Accordion title="Tunnel already running / port already in use">
    Only one tunnel can be active at a time. Stop the existing tunnel first:

    ```bash theme={null}
    decipher-tunnel kill
    ```

    Then start a new one with `decipher-tunnel forward -p <port>`.
  </Accordion>

  <Accordion title="'Not logged in' error">
    Your session may have expired. Log in again:

    ```bash theme={null}
    decipher-tunnel login
    ```

    If the issue persists, log out first and then log back in:

    ```bash theme={null}
    decipher-tunnel logout
    decipher-tunnel login
    ```
  </Accordion>

  <Accordion title="502 errors in the tunnel logs">
    This usually means your local dev server isn't running. Make sure your app is started and accessible at the port you forwarded before sending traffic through the tunnel.
  </Accordion>
</AccordionGroup>

***

*Need help? [Contact our support team](mailto:team@getdecipher.com).*