***

title: Connectivity
description: >-
Connect to GPU instances through shell, VS Code, and port forwarding with the
Brev CLI.
---------

Connect to your instances through shell, VS Code, or port forwarding.

<Callout intent="success">
  **SSH is fully managed**: The Brev CLI tracks instance hostnames and IP addresses automatically. Connect by instance name (`ssh my-instance` or `brev shell my-instance`) - you never need to look up or remember IP addresses.
</Callout>

## brev shell

Open an interactive SSH shell on your instance. Alias: `ssh`

```bash
brev shell my-instance

# Or use the ssh alias
brev ssh my-instance
```

This command opens an SSH connection to your instance. You'll land in `/home/ubuntu/workspace`.

### Flags

| Flag           | Description                                         |
| -------------- | --------------------------------------------------- |
| `--host`       | SSH into the host machine instead of the container. |
| `--dir` / `-d` | Override directory to launch shell.                 |

## brev open

Open your instance in VS Code, Cursor, Windsurf, or tmux.

```bash
# Open in VS Code (default)
brev open my-instance

# Open in specific editor
brev open my-instance cursor
brev open my-instance windsurf
brev open my-instance tmux

# Set default editor
brev open --set-default cursor
```

### Supported Editors

| Editor   | Command                                                 | Requirement                          |
| -------- | ------------------------------------------------------- | ------------------------------------ |
| VS Code  | `brev open my-instance` or `brev open my-instance code` | VS Code with Remote SSH extension.   |
| Cursor   | `brev open my-instance cursor`                          | Cursor installed in PATH.            |
| Windsurf | `brev open my-instance windsurf`                        | Windsurf installed in PATH.          |
| tmux     | `brev open my-instance tmux`                            | Installed automatically on instance. |

### Flags

| Flag            | Description                                         |
| --------------- | --------------------------------------------------- |
| `--host`        | SSH into the host machine instead of the container. |
| `--wait` / `-w` | Wait for setup to finish before opening.            |
| `--dir` / `-d`  | Specify directory to open.                          |
| `--set-default` | Set default editor (code, cursor, windsurf, tmux)   |

## brev port-forward

Forward ports from your instance to localhost. Essential for accessing Jupyter, web servers, and other services.

```bash
# Forward specific port (local:remote)
brev port-forward my-instance --port 8888:8888

# Forward multiple ports
brev port-forward my-instance --port 8888:8888 --port 6006:6006

# Interactive mode (prompts for ports)
brev port-forward my-instance
```

### How Port Forwarding Works

Port forwarding creates a secure tunnel from your local machine to your instance. The `local:remote` format means:

* **Local port**: The port on your machine (where you access the service)
* **Remote port**: The port on your instance (where the service runs)

For example, `--port 8888:8888` forwards localhost:8888 to instance:8888.

<Callout intent="tip">
  If a local port is already in use, choose a different local port: `--port 9999:8888` forwards localhost:9999 to instance:8888.
</Callout>

### Flags

| Flag     | Short | Description                           |
| -------- | ----- | ------------------------------------- |
| `--port` | `-p`  | Port mapping in format `local:remote` |
| `--host` |       | Use the host version of the instance. |

### Common Port Forwards

| Service     | Port   | Command            |
| ----------- | ------ | ------------------ |
| Jupyter     | `8888` | `--port 8888:8888` |
| TensorBoard | `6006` | `--port 6006:6006` |
| Streamlit   | `8501` | `--port 8501:8501` |
| Gradio      | `7860` | `--port 7860:7860` |

## Direct SSH

You can also connect directly with SSH using the Brev-managed key:

```bash
# Connect using instance name (configured by brev refresh)
ssh my-instance

# Or use the full SSH command
ssh -i ~/.brev/brev.pem ubuntu@<instance-ip>

# Manual port forward with SSH
ssh -i ~/.brev/brev.pem -p 22 -L LOCAL_PORT:localhost:REMOTE_PORT ubuntu@<instance-ip>
```

Where:

* `~/.brev/brev.pem` is your Brev private key
* `LOCAL_PORT` is the port on your local machine
* `REMOTE_PORT` is the port on your Brev instance
* `<instance-ip>` is your instance's public IP address

<Callout intent="tip">
  **SSH config:** Running `brev refresh` updates `~/.brev/ssh_config` with your instance details. This file is included from `~/.ssh/config` so you can connect by instance name.
</Callout>

## Using Tunnels (Web Console)

For publicly accessible URLs, use Brev's tunnel feature through the web console. This creates a shareable URL for your service.

<Steps>
  <Step title="Navigate to Instance Details">
    Open your instance in the Brev console.
  </Step>

  <Step title="Find Using Tunnels">
    Scroll to the **Access** section and locate **Using Tunnels**.
  </Step>

  <Step title="Add a Port">
    Enter the port number you want to expose (e.g., 8000 for an API server).
  </Step>

  <Step title="Copy the URL">
    Click the generated URL to copy it to your clipboard.
  </Step>
</Steps>

<Callout intent="warning">
  **Important Tunnel Limitations:**

  * Tunnels route through Cloudflare for authentication
  * First access requires browser authentication (redirect)
  * For direct API access without browser authentication, use `brev port-forward` instead
</Callout>

### When to Use Tunnels vs Port Forwarding

| Use Case                      | Recommended Method |
| ----------------------------- | ------------------ |
| Sharing with teammates        | Tunnels            |
| Web UIs (Jupyter, Gradio)     | Tunnels            |
| Direct API calls from scripts | Port forwarding    |
| CI/CD integrations            | Port forwarding    |
| Testing locally               | Port forwarding    |

## IP Address Changes

Instance IP addresses are stable while an instance is running. However, when you stop and restart an instance, it may receive a new IP address.

**The CLI handles this automatically** - run `brev refresh` after restarting an instance to update your local SSH config with the new IP.

```bash
brev refresh
```

This command:

* Fetches the latest IP addresses for all your instances
* Updates `~/.brev/ssh_config` with the new connection details
* Ensures you can connect by instance name without knowing the IP

<Callout intent="info">
  You only need to run `brev refresh` after stopping and restarting an instance. While an instance is running, its IP address remains the same.
</Callout>

You can verify the instance's current public IP by SSHing in and running:

```bash
curl ifconfig.me
```

## What's Next

<CardGroup cols={2}>
  <Card title="VS Code Setup" icon="window" href="/guides/development-tools/vscode-setup">
    Configure VS Code Remote SSH for full IDE features.
  </Card>

  <Card title="Jupyter Notebooks" icon="file" href="/guides/development-tools/jupyter-notebooks">
    Run JupyterLab with GPU acceleration.
  </Card>
</CardGroup>