# NVIDIA Brev Documentation

# NVIDIA Brev Documentation

> Get started with NVIDIA Brev - GPU-accelerated AI/ML development platform. Access configured GPU instances across multiple cloud providers.

NVIDIA Brev provides instant access to GPU instances preconfigured for AI and ML development across multiple cloud providers. Select a GPU, launch an instance, and start developing. Your GPU instance will include NVIDIA drivers, CUDA, Python, and Docker, all ready to use.

Launch your first GPU instance with the quickstart guide.

Set up VS Code Remote SSH to develop directly on your GPU instance.

Access JupyterLab on your GPU instance with port forwarding.

Run Docker and Docker Compose workloads on GPU instances.

Install and configure the Brev CLI for terminal-based workflows.

Run optimized NVIDIA inference microservices on your instance.

## Core Concepts

Preconfigured VMs with NVIDIA GPUs, Python, CUDA, Docker, and Jupyter ready to use.

One-click deployable environments. Bundle hardware, software, and code into shareable links.

Preinstalled AI/ML tools including Python, CUDA, Docker, Jupyter, and more.

## Popular Guides

| Level        | Guide                                                                    | Time     |
| ------------ | ------------------------------------------------------------------------ | -------- |
| Beginner     | [VS Code Remote SSH Setup](/guides/development-tools/vscode-setup)       | \~10 min |
| Beginner     | [Running Jupyter Notebooks](/guides/development-tools/jupyter-notebooks) | \~10 min |
| Intermediate | [Custom Docker Containers](/guides/development-tools/custom-containers)  | \~15 min |
| Advanced     | [Deploying NVIDIA NIMs](/guides/inference-deployment/deploying-nims)     | \~20 min |

# Quickstart

> Get your first GPU instance running with the NVIDIA Brev quickstart guide.

NVIDIA’s Brev platform simplifies GPU access by offering virtual machine instances with various GPU types. Instead of being limited to one cloud provider, Brev pulls resources from multiple providers, helping you find the right GPU setup for your workload.

Brev allows you to create, manage, and access your GPU instances.

This guide will help you build a fully configured GPU development environment and launch your first instance in three steps.

**Prefer point-and-click over the terminal?** This quickstart uses the Brev CLI, but you can do everything below from the web console at [brev.nvidia.com](https://brev.nvidia.com) instead. Refer to the [Console Reference](/guides/console-reference) for a walkthrough of creating instances, connecting through SSH, and exposing ports — all from the browser.

## Prerequisites

* A Brev account: [sign up at brev.nvidia.com](https://brev.nvidia.com)
* A terminal: (macOS Terminal, Linux shell, or Windows WSL)
* For macOS: [Homebrew](https://brew.sh) installed

The Brev CLI manages your GPU instances from the terminal. Choose from one of the following platforms:

```bash macOS
# Install with Homebrew
brew install brevdev/homebrew-brev/brev

# Verify installation
brev --version
```

```bash Linux
# Download and run the installer
sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/brevdev/brev-cli/main/bin/install-latest.sh)"

# Verify installation
brev --version
```

```powershell Windows
# First, install WSL with Ubuntu (run in PowerShell as admin)
wsl --install -d Ubuntu-22.04

# Restart your computer, then open Ubuntu and run:
sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/brevdev/brev-cli/main/bin/install-latest.sh)"

# Verify installation
brev --version
```

**Expected output:** You should see a version number printed, confirming the CLI is installed.

Log in to your Brev account. This opens your browser for authentication.

```bash
brev login
```

After logging in, your credentials are stored in `~/.brev/`. This directory also contains your SSH keys for connecting to instances.

**For headless environments:** Use `brev login --token` to authenticate with an API token instead of browser OAuth. Copy the command from the [CLI settings page](https://brev.nvidia.com/settings/cli).

{/* QUICKSTART_GPU: nebius.l40sx1.pcie */}

Create a GPU instance and open a shell session:

```bash
# Create a GPU instance with an NVIDIA L40S
brev create my-instance --gpu "nebius.l40sx1.pcie"

# Open a shell on your instance
brev shell my-instance
```

The `brev create` command provisions an instance with the specified GPU. This takes a few minutes while the instance starts. Once ready, `brev shell` opens a terminal session on the instance.

If you create an instance in the [Brev Console](https://brev.nvidia.com) instead, run `brev refresh` to sync it to your CLI, then `brev list` to see all your instances.

Refer to the [GPU Types catalog](/reference/gpu-types) for all available GPUs.

## Verify Your Setup

After connecting to your instance, verify the GPU is available:

```bash
nvidia-smi
```

You can see a table showing your GPU name (NVIDIA L40S), driver version, and CUDA version. This confirms the GPU is accessible and drivers are configured correctly.

## What's Next?

Set up VS Code Remote SSH for a full IDE experience.

Access JupyterLab with GPU acceleration through port forwarding.

Learn about instance lifecycle, states, and data persistence.

Explore all CLI commands for managing your instances.

# Core Concepts

> Understand the core concepts of NVIDIA Brev - GPU instances, launchables, and preconfigured environments.

NVIDIA Brev simplifies GPU development by combining three core concepts: GPU **Instances** provide the compute power, **Environments** deliver preconfigured software stacks, and **Launchables** bundle everything into shareable, one-click deployments.

These concepts work together to eliminate setup friction. When you deploy a Launchable, Brev provisions a GPU Instance with your chosen Environment already configured. There is no manual installation, no dependency conflicts, and no cloud console navigation. You go from link to working development environment in minutes.

Preconfigured virtual machines with NVIDIA GPUs. Learn about instance lifecycle, states, data persistence, and how billing works.

One-click deployable packages that bundle GPU hardware, software environments, and code into shareable links.

Preinstalled software stacks, including Python, CUDA, Docker, Jupyter, and IDE support for rapid development.

## Next Steps

Ready to start building? Follow the [Quickstart](/getting-started/quickstart) to launch your first GPU instance, or explore the concepts above to understand how Brev works.

# GPU Instances

> Learn about NVIDIA Brev GPU instances - lifecycle, states, data persistence, and billing.

Brev instances are GPU-equipped virtual machines preconfigured for AI/ML development. Each instance comes with Python, CUDA, Docker, and Jupyter preinstalled.

## What is a GPU Instance?

A GPU instance is a cloud virtual machine with one or more NVIDIA GPUs attached. Brev abstracts away the complexity of cloud setup, giving you instant access to configured development environments across multiple cloud providers.

* NVIDIA GPU(s) with CUDA drivers
* Python 3.10+ with pip
* Docker and Docker Compose
* JupyterLab
* SSH access

Brev supports a wide range of NVIDIA GPUs. Refer to [GPU Types](/reference/gpu-types) for the complete catalog with specifications and recommended use cases.

## Instance Lifecycle

Instances move through several states during their lifetime. Understanding these states helps you manage costs and data.

```
Create → Running ⇄ Stopped → Deleted
```

### Running

The instance is active and accessible. Brev bills you per hour for compute time. Connect with [SSH](/cli/connectivity), shell, or [VS Code](/guides/development-tools/vscode-setup).

### Stopped

When you stop an instance, Brev releases the GPU back to the cloud provider while preserving your data. You avoid compute charges, but your data remains bound to the original provider and region.

**What happens when you stop:**

* Brev releases the GPU to the provider's pool
* Your data in `/home/ubuntu/workspace` persists on the provider's storage
* No compute charges while stopped (minimal storage costs apply)

**Restarting a stopped instance:**

* Brev attempts to provision the same GPU type in the same provider and region
* If capacity is unavailable, the restart fails, and your data remains inaccessible
* You must wait for capacity or delete the instance (losing data)

Use [`brev start`](/cli/instance-management) to resume a stopped instance.

**Capacity risk:** GPU availability varies by provider and region. Popular GPU types frequently hit capacity limits. If you stop an instance and capacity becomes unavailable, you cannot access your data until capacity returns. Push important work to Git before stopping.

### When to Stop, When to Delete

Consider your situation before choosing:

| Scenario                      | Recommendation    | Why                                               |
| ----------------------------- | ----------------- | ------------------------------------------------- |
| Short break (hours)           | Stop              | Likely to get same capacity back.                 |
| Overnight or weekend          | Stop with caution | Push work to Git first; capacity may change.      |
| Extended break (days or more) | Delete            | Avoid storage costs and capacity lock-in.         |
| Switching GPU types           | Delete            | Stopped instances cannot change GPU type.         |
| Need maximum flexibility      | Delete            | No provider or region constraints on next launch. |

### Deleted

Brev permanently deletes (removes) the instance and all data. You cannot undo this action.

## Data Persistence

Understanding where data persists helps you avoid losing work.

| Location                 | Persists on Stop? | Persists on Delete? |
| ------------------------ | ----------------- | ------------------- |
| `/home/ubuntu/workspace` | Yes               | No                  |
| `/tmp`                   | No                | No                  |
| System packages          | Yes               | No                  |
| Docker images/containers | Yes               | No                  |

**Best practice:** Store all your work in `/home/ubuntu/workspace` and push to a Git remote regularly. Use Docker volumes for persistent container data.

## Billing

* **Running:** Brev bills per hour based on GPU type
* **Stopped:** No compute charges (minimal storage costs apply)
* **Deleted:** No charges

If your organization runs out of credits, Brev may stop stoppable running instances and delete non-stoppable resources. If credits are not added during the grace period, Brev may delete remaining resources. Deleted instances and their data cannot be recovered. See [Billing & Usage](/guides/console-reference#billing--usage) for details.

# Launchables

> Learn about NVIDIA Brev Launchables - one-click deployable GPU environments that bundle hardware, software, and code.

Launchables bundle GPU hardware, software environments, and code into one-click deployable packages. Share a link, and anyone can spin up an identical environment.

## What are Launchables?

A Launchable is a reproducible, shareable GPU environment configuration. It captures everything needed to run a specific workload:

* **Hardware requirements:** GPU type, memory, disk space
* **Software stack:** Base image, dependencies, setup scripts
* **Code:** Git repository, notebooks, or embedded files
* **Networking:** Exposed ports, Jupyter settings

**Use cases:** Tutorials, demos, workshops, team onboarding, reproducing research, and distributing GPU applications.

## Creating a Launchable

Create a Launchable in the [Brev Console](https://brev.nvidia.com) using the a step-by-step wizard.

### Step 1: Files and Runtime

Choose how to add code files and select a runtime mode for your Launchable:

**Code source:**

| Option                    | Description                                    | Best for                        |
| ------------------------- | ---------------------------------------------- | ------------------------------- |
| **Git Repository**        | Link a public repository URL or notebook link. | Open-source projects, tutorials |
| **Embedded in Container** | Code is already in the container image.        | Custom Docker images            |
| **No Code**               | Empty GPU sandbox environment.                 | Exploration, ad-hoc work        |

**Runtime mode:**

| Mode          | Description                                                                          |
| ------------- | ------------------------------------------------------------------------------------ |
| **VM Mode**   | Run directly on the GPU VM with Ubuntu 22.04. Docker, Python, and CUDA preinstalled. |
| **Container** | Run in a Docker container or Docker Compose stack.                                   |

**Private Repositories**: If you need to pull from a private registry or require API keys, select **VM Mode** runtime and handle authentication in a setup script.

### Step 2: Configure Environment

This step changes based on the runtime mode selected in Step 1:

You are prompted: **Do you want to run a setup script?**

* Upload or paste a bash setup script to customize the environment (install dependencies, configure services)
* Full SSH access to the instance

You are prompted: **Choose a Container Configuration**

* **Featured Containers**: Prebuilt images for common AI/ML frameworks (recommended for simple demos)
* **Docker Compose**: For complex, multi-container workflows
* If using Docker Compose, validate your configuration before proceeding

### Step 3: Jupyter and Networking

Configure access and networking:

**Jupyter Notebook Experience**:

* **Yes**: NVIDIA Brev installs Jupyter on the host and provides a one-click button to access code through JupyterLab.
* **No**: Users access the instance with SSH using the Brev CLI.

**Network Configuration**:

* **Secure Links**: Preconfigure Cloudflare tunnel URLs for specific ports.
* **TCP/UDP Ports**: Specify ports and assign access permissions.

### Step 4: Compute Configuration

Select hardware for your Launchable:

1. Choose an **NVIDIA GPU** based on your workload requirements.
2. Filter by VRAM, cloud provider, compute attributes, or price.
3. Adjust **disk storage** based on data and model size needs.

Select the minimum-cost configuration that meets your requirements. Users choose different hardware when deploying, if needed.

### Step 5: Final Review

Complete your Launchable:

1. Enter a **Name** for your Launchable.
2. Set **View Access** to control who can see and deploy your Launchable:
   * **Publish to community** toggle. Turn on to make the Launchable discoverable by all users in the Explore search results.
   * With the toggle off, choose between **Anyone with the link** (default) or **Only my organization**.
3. **Preview** the deployment page to see what users will experience.
4. Click **Create Launchable** to generate your shareable link.

## Runtime Modes

Choose how your Launchable configures the instance environment:

Run directly on the instance with setup scripts. Best for simple configurations and when you need full VM access.

* Bash setup scripts
* apt/pip dependencies
* Full SSH access

Run in a Docker container or Docker Compose stack. Best for reproducible, isolated environments.

* Custom Dockerfiles
* Docker Compose stacks
* Prebuilt images (NGC, Docker Hub)

## Exploring Launchables

The **Launchables** tab in the [Brev Console](https://brev.nvidia.com) provides a fully indexed, searchable collection of shared launchables. Browse curated picks or search to find GPU environment templates you can deploy with one click.

### Browsing

When you open the **Explore** view within the **Launchables** tab, the page displays curated sections:

* **Featured**: Hand-picked launchables highlighted with a blue badge (up to six shown).
* **Trending This Week**: Popular launchables ranked by recent activity (up to three shown, with green rank badges).
* **All Time Popular**: Most popular launchables overall (up to six shown, with yellow rank badges).

Each launchable card displays: name, author, description, cost per hour, view count, and deploy count. Click any card to go directly to the deploy page.

A row of cloud provider logos shows available compute backing (AWS, Google Cloud, Crusoe, Lambda, Nebius, Hyperstack, Oracle, and others).

### Searching and Filtering

The search bar accepts free-text queries across launchable names, containers, models, workflows, and GPUs. Press **Enter** or click the search icon to execute.

Two optional filters narrow results further:

| Filter             | Description                                                                        |
| ------------------ | ---------------------------------------------------------------------------------- |
| **GPU Name**       | Filter by specific GPU type (dynamically populated from available instance types). |
| **Cloud Provider** | Filter by cloud provider, such as AWS or GCP.                                      |

Changing a filter triggers an immediate search. Active filters appear as dismissible badges below the search bar. Click **Clear all** to reset and return to the curated browse view.

Results display in a responsive grid with infinite scroll (results load automatically as you scroll).

You can deep-link to filtered results by adding query parameters: `?gpuType=A100` or `?cloud=AWS`. This is useful for embedding links in documentation or READMEs that take users directly to relevant launchables.

### Sharing and Access Levels

Control who can view and deploy your launchables with three access levels:

| Access Level     | Visibility                                           | Use Case                                  |
| ---------------- | ---------------------------------------------------- | ----------------------------------------- |
| **Organization** | Only members of your organization.                   | Team collaboration, internal tools        |
| **Link sharing** | Anyone with the direct link.                         | Workshops, selective distribution.        |
| **Published**    | Discoverable by all users in Explore search results. | Open-source projects, community resources |

Set visibility during creation in the final review step, or change it later from the **My Launchables** tab. New launchables default to **Anyone with the link**. To make a launchable discoverable in Explore, turn on **Publish to community**.

## Managing Launchables

All your Launchables display under the **Launchables** tab. From there, you can:

| Action                  | Description                                                                                                                                                                                                                                      |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **View Metrics**        | See views and deployment counts for each Launchable.                                                                                                                                                                                             |
| **Change Access**       | Change visibility between Organization, Link sharing, and Published. Switching to Published opens a publish confirmation; switching away from Published shows an unpublish warning that the Launchable will no longer display in search results. |
| **Preview**             | See the deployment page that users will experience.                                                                                                                                                                                              |
| **Copy Markdown Badge** | Embed a "Launch on Brev" button in READMEs and documentation.                                                                                                                                                                                    |
| **Show Configuration**  | View hardware and software details.                                                                                                                                                                                                              |
| **Delete**              | Permanently remove a Launchable.                                                                                                                                                                                                                 |

### Embedding Launchables

Add a launch badge to any markdown file to let users deploy with one click:

```markdown
[![Launch on Brev](https://brev-assets.s3.us-west-1.amazonaws.com/nv-lb-dark.svg)](https://brev.nvidia.com/launchable/deploy?launchableID=your-launchable-id)
```

## What's Next

Learn about preconfigured software environments.

Run Docker workloads with GPU access.

# Environments

> Learn about preconfigured software environments in NVIDIA Brev GPU instances.

Every Brev instance provides a development environment with popular AI/ML tools ready to use. There is no manual setup required.

## What's Included

What's preinstalled depends on your [deployment mode](/concepts/launchables):

| Mode               | Environment                    | Preinstalled Software                                |
| ------------------ | ------------------------------ | ---------------------------------------------------- |
| **VM Mode**        | Full Ubuntu VM                 | Python 3.10+, CUDA, Docker, NVIDIA Container Toolkit |
| **Container Mode** | Single Docker container        | Depends on your base image.                          |
| **Compose Mode**   | Multi-container Docker Compose | Depends on service images.                           |

Refer to [Launchables](/concepts/launchables) for details on choosing the right deployment mode.

### VM Mode Software

VM Mode instances include:

* **Languages**: Python 3.10+ with pip (version configurable)
* **GPU Support**: CUDA Toolkit, cuDNN, NVIDIA drivers
* **Containers**: Docker, Docker Compose, NVIDIA Container Toolkit
* **Notebooks**: JupyterLab (when enabled in configuration)

### Container and Compose Modes

Preinstalled software depends on your base image. Common NVIDIA base images include PyTorch, TensorFlow, and TensorRT containers from [NGC](https://catalog.ngc.nvidia.com/).

* VS Code Remote SSH
* Cursor
* Windsurf

- Git version control
- SSH access
- Brev CLI

## CUDA and GPU Support

Brev preconfigures and optimizes NVIDIA drivers and CUDA for your GPU type. Verify GPU access with:

```bash
# Quick check - GPU and CUDA availability
nvidia-smi
nvcc --version

# Framework verification (requires PyTorch installed)
pip install torch  # if not using a PyTorch base image
python3 -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}')"
python3 -c "import torch; print(f'GPU: {torch.cuda.get_device_name(0)}')"
```

## Working Directory

Your default working directory is `/home/ubuntu/workspace`. This is where you should store all your work, as it persists across instance stops.

The default username is `ubuntu` for most providers. Your working directory path is `/home/<username>/workspace`.

```bash
# Navigate to workspace
cd /home/ubuntu/workspace

# Clone your project
git clone https://github.com/your/repo.git

# Create a virtual environment
python3 -m venv .venv
source .venv/bin/activate
```

## Customizing Your Environment

You have full control to install additional packages and configure the environment:

```bash
# Navigate to workspace
cd /home/ubuntu/workspace

# Install Python packages
pip install transformers accelerate

# Install system packages
sudo apt update && sudo apt install -y htop

# Pull Docker images
docker pull nvcr.io/nvidia/pytorch:24.01-py3
```

System packages and Docker images persist across instance stops. Create a setup script or Dockerfile for reproducibility.

## What's Next

Install and configure the Brev CLI.

Run JupyterLab with GPU acceleration.

# Registered Compute

> Register external hardware like DGX Spark and DGX Station with NVIDIA Brev for SSH access, team sharing, and port forwarding.

Registered Compute lets you bring your own hardware into NVIDIA Brev. Register any Linux machine — DGX Spark, DGX Station, or any other node — to get SSH access, team sharing, and port forwarding through the Brev platform.

## What is Registered Compute?

Registered Compute connects your physical hardware to Brev's management layer. Once registered, your machine appears in the Brev console alongside cloud GPU instances, and your team can connect to it using the same CLI commands.

This is designed for hardware you own and manage — Brev handles connectivity and access control, not the machine's lifecycle.

## How It Works

Registration is a single CLI command that performs three steps:

1. **Installs NetBird** — A mesh VPN agent that provides secure connectivity between your machine and Brev users
2. **Profiles hardware** — Auto-detects GPUs (via NVML), CPU, RAM, storage, OS, and interconnects like NVLink and PCIe
3. **Registers with Brev** — Makes the machine visible in your Brev organization

After registration, you enable SSH access and can share the machine with teammates.

```
Register → NetBird installed → Hardware profiled → Node appears in Brev
    ↓
Enable SSH → Share with team → Connect via brev shell
```

## Registered Compute vs Cloud GPU Instances

| Feature                     | Registered Compute | Cloud GPU Instances |
| --------------------------- | ------------------ | ------------------- |
| SSH access                  | Yes                | Yes                 |
| Team sharing                | Yes                | Yes                 |
| Port forwarding             | Yes                | Yes                 |
| Hardware auto-detection     | Yes                | N/A (predefined)    |
| Launchables                 | No                 | Yes                 |
| Managed environments        | No                 | Yes                 |
| Start/stop/delete lifecycle | No                 | Yes                 |
| Billing                     | No compute charges | Per-hour billing    |

## Supported Hardware

Registered Compute works with any Linux machine. Primary use cases include:

* **NVIDIA DGX Spark** — Desktop AI workstation
* **NVIDIA DGX Station** — Multi-GPU workstation with NVLink
* **Any Linux node** — Any machine running a supported Linux distribution

### Hardware Auto-Detection

During registration, Brev automatically profiles your machine and detects:

* **GPUs** — Model, count, and memory via NVML
* **CPU** — Architecture, model, and core count
* **RAM** — Total system memory
* **Storage** — Available disk space
* **Interconnects** — NVLink and PCIe topology
* **OS** — Distribution and version
* **Product name** — e.g., "DGX Spark", "DGX Station"

This profile is visible in the Brev console and helps teammates understand the machine's capabilities.

## Registration Data

Registration state is stored locally at `/etc/brev/device_registration.json`. This file is created during `brev register` and removed during `brev deregister`.

Registration requires `sudo` access because NetBird is installed as a system service via systemd.

## Next Steps

Step-by-step guide to register your DGX Spark with Brev.

Register a DGX Station with multi-GPU and NVLink support.

Share access, forward ports, and deregister machines.

Complete command reference for registered compute.

# CLI Reference

> Complete reference for the NVIDIA Brev CLI. Search for GPUs, create instances, connect, and automate workflows from your terminal.

The Brev CLI provides full control over your GPU and CPU instances from the command line. Search for hardware, create instances, connect via shell or editor, and chain commands together with composable pipes.

**SSH is fully managed**: The CLI automatically handles SSH keys, config files, and IP addresses. Just run `ssh my-instance` or `brev shell my-instance` to connect. There is no manual configuration needed.

## First Time?

Follow the [installation instructions](/cli/getting-started#installation) for your platform.

Run `brev login` to authenticate. This sets up your SSH keys automatically.

Run `brev start https://github.com/user/repo.git` to create an instance, or `brev refresh` to sync instances from the web console.

Run `brev shell my-instance` or `ssh my-instance` to connect.

## Quick Start

```bash
# Get help on any command
brev --help
brev <command> --help

# Check CLI version
brev --version
```

## Command Reference

Commands organized by what you want to do:

### Getting Started

| Command   | Description                          |
| --------- | ------------------------------------ |
| `login`   | Authenticate with your Brev account. |
| `logout`  | Remove stored credentials.           |
| `ssh-key` | Display your SSH public key.         |

### Search & Create

| Command  | Description                                               |
| -------- | --------------------------------------------------------- |
| `search` | Search GPU and CPU instance types with filters.           |
| `create` | Create instances with smart defaults and fallback chains. |

### Managing Instances

| Command   | Description                                            |
| --------- | ------------------------------------------------------ |
| `ls`      | List instances in current organization (alias: `list`) |
| `start`   | Start stopped instances.                               |
| `stop`    | Stop running instances (supports `--all`)              |
| `delete`  | Delete an instance permanently                         |
| `refresh` | Sync instances from web console                        |

### Connecting

| Command        | Description                                             |
| -------------- | ------------------------------------------------------- |
| `shell`        | Open interactive SSH shell                              |
| `exec`         | Run commands on instances non-interactively             |
| `copy`         | Copy files to/from instances (aliases: `cp`, `scp`)     |
| `open`         | Open instance in VS Code, Cursor, Windsurf, or terminal |
| `port-forward` | Forward remote ports to localhost                       |

### Organizations

| Command  | Description                 |
| -------- | --------------------------- |
| `org ls` | List your organizations.    |
| `set`    | Switch active organization. |
| `invite` | Generate an invite link.    |

### Agent Integration

| Command       | Description                                            |
| ------------- | ------------------------------------------------------ |
| `agent-skill` | Install/uninstall the Brev skill for AI coding agents. |

## Detailed Documentation

Installation, authentication, and basic configuration.

Create instances with smart defaults, fallback chains, and startup scripts.

List, start, stop, delete, reset, and refresh commands.

Shell, exec, copy, editor access, and port forwarding.

Find GPU and CPU instance types with powerful filtering and sorting.

Chain commands with pipes for powerful automation.

Additional commands: org, reset, create, invite, copy, status.

# CLI Getting Started

> Install and configure the NVIDIA Brev CLI for terminal-based GPU instance management.

Install and configure the Brev CLI for terminal-based GPU instance management.

## Installation

### macOS

```bash
# Add the Brev tap and install
brew install brevdev/homebrew-brev/brev

# Verify installation
brev --version
```

### Linux

```bash
# Download and run the installer
sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/brevdev/brev-cli/main/bin/install-latest.sh)"

# Verify installation
brev --version
```

### Windows (WSL)

Brev supports Windows through the Windows Subsystem for Linux (WSL).

**Prerequisites:**

* [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) installed and configured
* Virtualization enabled in your BIOS settings
* Ubuntu 20.04 or later from the Microsoft Store

```powershell
# Install WSL with Ubuntu (run in PowerShell as admin)
wsl --install -d Ubuntu-22.04

# Restart your computer, then open Ubuntu and run:
sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/brevdev/brev-cli/main/bin/install-latest.sh)"
```

**BIOS Virtualization**: If WSL fails to start, ensure virtualization (VT-x/AMD-V) is enabled in your BIOS settings. The exact steps vary by motherboard manufacturer.

## Authentication

### brev login

Authenticate with your Brev account. Opens a browser window for OAuth login and creates the `~/.brev/` directory with your credentials and SSH keys.

```bash
# Standard login (opens browser)
brev login

# Login with token (for headless/CI environments)
brev login --token

# Skip browser auto-open
brev login --skip-browser
```

### Flags

| Flag             | Description                                              |
| ---------------- | -------------------------------------------------------- |
| `--token`        | Authenticate with a token (for headless/CI environments) |
| `--skip-browser` | Print URL instead of auto-opening browser.               |
| `--email`        | Email to use for authentication (NVIDIA auth only)       |
| `--auth`         | Authentication provider: `nvidia` (default) or `legacy`  |

### brev logout

Remove stored credentials from your machine.

```bash
brev logout
```

### brev ssh-key

Display your Brev SSH public key. Use this to add to Git providers like GitHub or GitLab.

```bash
# Display your public SSH key
brev ssh-key

# Copy to clipboard (macOS)
brev ssh-key | pbcopy
```

## How the CLI Manages SSH

The Brev CLI handles all SSH configuration automatically. You never need to:

* Track instance IP addresses
* Manage SSH keys
* Edit SSH config files

After logging in, the CLI:

1. Downloads your SSH key to `~/.brev/brev.pem`
2. Adds your instances to `~/.brev/ssh_config`
3. Keeps the config in sync as instances start and stop

**Connect by name, not IP**: Run `ssh my-instance` or `brev shell my-instance`. The CLI tracks the IP address for you.

### What's in \~/.brev/

| File               | Purpose                             |
| ------------------ | ----------------------------------- |
| `brev.pem`         | Your SSH private key.               |
| `ssh_config`       | SSH entries for all your instances. |
| `credentials.json` | Your authentication tokens.         |

Run `brev refresh` after creating instances in the web console to sync them to your local CLI and SSH config.

## Understanding Your Environment

When you connect to a Brev instance, you're connecting to a containerized environment running on a GPU VM.

| Component     | Description                                                                      |
| ------------- | -------------------------------------------------------------------------------- |
| **Container** | Your development environment with Python, CUDA, etc. Default SSH target.         |
| **Host**      | The underlying GPU VM. Use `--host` flag to access.                              |
| **workspace** | Your persistent workspace at `/home/ubuntu/workspace`. Files here survive stops. |

Store all your work in `/home/ubuntu/workspace` and push to Git regularly. This directory persists when you stop an instance, but is deleted when you delete the instance.

## What's Next

Learn to list, start, stop, and delete instances.

Connect through shell, VS Code, or port forwarding.

# Instance Creation

> Create GPU and CPU instances with smart defaults, fallback chains, startup scripts, and composable piping using the Brev CLI.

Create instances with automatic GPU type selection, fallback chains, startup scripts, and composable piping.

## brev create

```bash
brev create [name] [flags]
```

**Aliases:** `provision`, `gpu-create`, `gpu-retry`, `gcreate`

## Flags

| Flag               | Short | Description                                            |
| ------------------ | ----- | ------------------------------------------------------ |
| `--name`           | `-n`  | Instance name.                                         |
| `--type`           | `-t`  | Comma-separated instance types to try (fallback chain) |
| `--count`          | `-c`  | Number of instances to create (default: 1)             |
| `--parallel`       | `-p`  | Parallel creation attempts (default: 1)                |
| `--startup-script` | `-s`  | Script to run on boot (inline string or `@filepath`)   |
| `--timeout`        |       | Seconds to wait for ready (default: 300)               |
| `--detached`       | `-d`  | Don't wait for instance to be ready.                   |
| `--dry-run`        |       | Show matching instance types without creating.         |

### Search Filter Flags

All [search filter flags](/cli/search-discovery) are also available on `brev create`:

| Flag               | Short | Description                                |
| ------------------ | ----- | ------------------------------------------ |
| `--gpu-name`       | `-g`  | Filter by GPU name (partial match)         |
| `--provider`       |       | Filter by cloud provider.                  |
| `--min-vram`       | `-v`  | Minimum VRAM per GPU (GB)                  |
| `--min-total-vram` |       | Minimum total VRAM (GB)                    |
| `--min-capability` |       | Minimum GPU compute capability.            |
| `--min-disk`       |       | Minimum disk size (GB)                     |
| `--max-boot-time`  |       | Maximum boot time (minutes)                |
| `--stoppable`      |       | Only stoppable instances.                  |
| `--rebootable`     |       | Only rebootable instances.                 |
| `--flex-ports`     |       | Only instances with configurable firewall. |
| `--sort`           |       | Sort by: price, vram, boot-time, etc.      |
| `--desc`           |       | Sort descending.                           |

## Smart Defaults

When you run `brev create` without specifying `--type` or any filter flags, the CLI applies these defaults:

* **20 GB** minimum total VRAM
* **500 GB** minimum disk
* **Compute 8.0+** (Ampere or newer)
* **\< 7 min** boot time
* Sorted by **price** (cheapest first)

```bash
# Uses smart defaults — picks the cheapest GPU matching the above criteria
brev create my-instance
```

## Specifying Instance Types

### Single Type

```bash
brev create my-instance --type g5.xlarge
```

### Fallback Chain

Provide a comma-separated list of types. The CLI tries each in order until one succeeds:

```bash
brev create my-instance --type g5.xlarge,g5.2xlarge,g5.4xlarge
```

### Using Search Filters

Apply the same filters available in `brev search` to narrow the type selection:

```bash
brev create my-instance --gpu-name A100 --min-vram 40
```

### Piping from Search

Pipe `brev search` output directly into `brev create`:

```bash
brev search --gpu-name A100 | brev create my-instance
```

## Startup Scripts

Run scripts or commands automatically when the instance boots.

### Inline Script

```bash
brev create my-instance -s 'pip install torch'
```

### File Reference (`@filepath` Syntax)

Prefix a local file path with `@` to use its contents as the startup script:

```bash
brev create my-instance -s @setup.sh
brev create my-instance -s @./scripts/install-deps.sh
```

## Clusters

Create multiple instances at once with `--count`:

```bash
brev create my-cluster --count 3 --type g5.xlarge
```

## Dry Run

Preview matching instance types without actually creating anything:

```bash
brev create my-instance --dry-run
brev create my-instance --gpu-name A100 --dry-run
```

## Detached Mode

Skip waiting for the instance to be ready:

```bash
brev create my-instance --detached
```

## Output Piping

`brev create` outputs the instance name to stdout, enabling chaining with other commands:

```bash
# Create and open in an editor
brev create my-instance | brev open cursor

# Create and run a command
brev create my-instance | brev exec "nvidia-smi"

# Create and run a setup script
brev create my-instance | brev exec @setup.sh

# Full pipeline: search, create, open
brev search --gpu-name A100 | brev create my-box | brev open cursor
```

## Examples

```bash
# Simple creation with smart defaults
brev create my-instance

# Specific type with startup script
brev create my-instance --type g5.xlarge -s @setup.sh

# High-VRAM GPU with fallback
brev create training-box --gpu-name A100 --min-vram 40

# Create 3-node cluster
brev create my-cluster --count 3 --type g5.xlarge

# Preview what would be created
brev create my-instance --dry-run

# Full pipeline: search → create → setup → open
brev search --gpu-name A100 | brev create my-box | brev exec @setup.sh
```

# Instance Management

> Manage GPU instance lifecycle with Brev CLI - list, start, stop, delete, and refresh commands.

Commands for managing the lifecycle of your GPU instances.

## brev list

List workspaces and organizations.

```bash
# List instances in current organization
brev list

# List all organizations you belong to
brev list orgs

# List instances in a specific organization
brev list --org my-team
```

## brev start

Start a stopped instance, or create a new one from a Git URL or local path.

**`brev start` vs `brev create`**: These commands are equivalent. Use `brev start` as it is the preferred command.

### Start a Stopped Instance

```bash
brev start my-instance
```

### Create from Git URL

```bash
# Create from GitHub
brev start https://github.com/user/repo.git

# With custom name
brev start https://github.com/user/repo.git --name my-project

# In a specific organization
brev start https://github.com/user/repo.git --org my-team
```

### Create with GPU

```bash
# Default GPU (T4)
brev start https://github.com/user/repo.git

# Specify GPU type
brev start https://github.com/user/repo.git --gpu "n1-highmem-4:nvidia-tesla-a100:1"
```

#### GPU Type Format

The `--gpu` flag uses the format `machine-type:gpu-type:count`:

| Part         | Description      | Example             |
| ------------ | ---------------- | ------------------- |
| machine-type | Cloud VM type    | `n1-highmem-4`      |
| gpu-type     | NVIDIA GPU model | `nvidia-tesla-a100` |
| count        | Number of GPUs   | `1`                 |

Refer to [GPU Instances](/concepts/gpu-instances) for available GPU types and pricing.

### Create Empty Instance

```bash
brev start --name my-sandbox
```

### Flags

| Flag             | Short | Description                         |
| ---------------- | ----- | ----------------------------------- |
| `--name`         | `-n`  | Name for the new instance.          |
| `--org`          | `-o`  | Organization (overrides active org) |
| `--gpu`          | `-g`  | GPU instance type.                  |
| `--detached`     | `-d`  | Run in background without blocking. |
| `--empty`        | `-e`  | Create empty instance (no Git repo) |
| `--setup-script` | `-s`  | URL to setup script.                |
| `--setup-repo`   | `-r`  | Repo containing setup script.       |
| `--setup-path`   | `-p`  | Path to setup script.               |

### Using Setup Scripts

Setup scripts run automatically after your instance starts. Use them to install dependencies or configure your environment.

```bash
# Run a setup script from URL
brev start https://github.com/user/repo.git --setup-script https://raw.githubusercontent.com/user/repo/main/setup.sh

# Run a script from within the repo
brev start https://github.com/user/repo.git --setup-repo . --setup-path ./scripts/setup.sh
```

Setup scripts run as the default user. Use `sudo` for system-level installations.

## brev stop

Pause an instance. Data in `/home/ubuntu/workspace` persists between stops.

```bash
# Stop a single instance
brev stop my-instance

# Stop multiple instances
brev stop instance-1 instance-2 instance-3

# Stop all your instances
brev stop --all
```

### Flags

| Flag    | Short | Description                                 |
| ------- | ----- | ------------------------------------------- |
| `--all` | `-a`  | Stop all your instances in the current org. |

## brev delete

Permanently remove an instance and all its data.

```bash
# Delete by name
brev delete my-instance

# Delete by ID
brev delete abc123def456

# Delete multiple instances
brev delete instance-1 instance-2
```

Deleting an instance is irreversible. All data is permanently lost.

## brev refresh

Sync instances and update your local SSH configuration. The CLI manages SSH config automatically, but run this command to force an immediate sync.

```bash
brev refresh
```

**What refresh does:**

1. Downloads instances created in the web console
2. Updates `~/.brev/ssh_config` with current instance IPs
3. Ensures `~/.brev/brev.pem` has correct permissions

**After refresh, connect by name**: Run `ssh my-instance` or `brev shell my-instance`. You never need to look up IP addresses.

**When to refresh:** After creating instances in the web console, after restarting a stopped instance (IP may change), or when SSH connections fail.

## brev set

Change the active organization context. All subsequent commands will operate within this org.

```bash
brev set my-team
```

To switch organizations, you must be logged in. Use `brev login` first if needed.

## What's Next

Connect through shell, VS Code, or port forwarding.

Additional commands for power users.

# Registered Compute Commands

> CLI reference for registering external hardware, managing SSH access, and deregistering machines from NVIDIA Brev.

Commands for registering external hardware with Brev, managing SSH access, and deregistering machines.

For connectivity commands (`brev shell` and `brev port-forward`) that also work with registered compute, see [Connectivity](/cli/connectivity).

## brev register

Register a Linux machine with your Brev organization. This installs the NetBird mesh VPN, profiles the machine's hardware, and registers it with the Brev API.

```bash
brev register -n <name>
```

### Flags

| Flag     | Short | Description                                            |
| -------- | ----- | ------------------------------------------------------ |
| `--name` | `-n`  | Display name for the machine (e.g., "My DGX Spark")    |
| `--org`  | `-o`  | Organization to register with (defaults to active org) |

### What it does

1. Installs the NetBird VPN agent via `https://pkgs.netbird.io/install.sh`
2. Collects a hardware profile — GPUs (NVML), CPU, RAM, storage, OS, interconnects
3. Registers the machine with the Brev API

### Example

```bash
# Register with a name
brev register -n "My DGX Spark"

# Register to a specific organization
brev register --name "Lab Workstation" --org my-team
```

Requires `sudo` access. Linux only. The NetBird agent is installed as a systemd service.

## brev enable-ssh

Enable SSH access on a registered machine for the current user. Prompts for the SSH port to use.

```bash
brev enable-ssh
```

### Flags

No flags. Prompts interactively for the SSH port.

### Details

* Grants SSH access to yourself (a "reflexive grant")
* Checks if the SSH daemon (`ssh` or `sshd`) is running and warns if it's not active
* Must be run on a registered machine

### Example

```bash
$ brev enable-ssh
Enter SSH port: 22
SSH enabled successfully.
```

## brev grant-ssh

Grant SSH access to another member of your organization. Presents an interactive selector to choose the user.

```bash
brev grant-ssh
```

### Flags

No flags. Interactive user selector. Prompts for SSH port.

### Example

```bash
$ brev grant-ssh
Select a user to grant SSH access:
> alice@example.com
  bob@example.com
```

Requires SSH to already be enabled on the device (run `brev enable-ssh` first). This command removes `~/.brev/credentials.json` before granting access to prevent the other user from seeing the device owner's auth tokens.

## brev revoke-ssh

Revoke SSH access from a user. Presents an interactive selector showing Brev-managed SSH keys with a key preview and associated user.

```bash
brev revoke-ssh
```

### Flags

No flags. Interactive key selector.

### How it works

Revocation is two-stage:

1. Removes the SSH key from the local machine
2. Sends an RPC to the Brev server to revoke server-side access

### Example

```bash
$ brev revoke-ssh
Select a key to revoke:
> SHA256:abc123... (alice@example.com)
  SHA256:def456... (bob@example.com)
```

## brev deregister

Remove the current machine from Brev. Performs a full cleanup.

```bash
brev deregister
```

### Flags

No flags. Prompts for confirmation.

### What it does

1. Unregisters the machine from the Brev server
2. Removes SSH keys
3. Uninstalls the NetBird agent
4. Deletes `/etc/brev/device_registration.json`

### Example

```bash
$ brev deregister
Are you sure you want to deregister this machine? [y/N]: y
Machine deregistered successfully.
```

## Using shell and port-forward with Registered Compute

The `brev shell` and `brev port-forward` commands work with registered compute nodes. If a workspace with the given name isn't found, Brev automatically falls back to looking up registered external nodes.

```bash
# SSH into a registered machine
brev shell my-dgx-spark

# Forward a port from a registered machine
brev port-forward my-dgx-spark --port 8888:8888
```

Port forwarding supports TCP and UDP protocols via the `OpenPort` RPC.

# Connectivity

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

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

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

If a local port is already in use, choose a different local port: `--port 9999:8888` forwards localhost:9999 to instance:8888.

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

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

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

Open your instance in the Brev console.

Scroll to the **Access** section and locate **Using Tunnels**.

Enter the port number you want to expose (e.g., 8000 for an API server).

Click the generated URL to copy it to your clipboard.

**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

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

You only need to run `brev refresh` after stopping and restarting an instance. While an instance is running, its IP address remains the same.

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

```bash
curl ifconfig.me
```

## What's Next

Configure VS Code Remote SSH for full IDE features.

Run JupyterLab with GPU acceleration.

# Search & Discovery

> Find GPU and CPU instance types with filtering, sorting, and structured output using the Brev CLI.

Search for available instance types across cloud providers, filter by hardware specs, and pipe results directly into `brev create`.

## brev search

```bash
brev search [gpu|cpu] [flags]
```

**Aliases:** `gpu-search`, `gpu`, `gpus`, `gpu-list`

The `search` command has two subcommands:

* `brev search` or `brev search gpu` — GPU instances (default)
* `brev search cpu` — CPU-only instances

## GPU Search

Search for GPU instance types with filtering by GPU model, VRAM, compute capability, and more.

```bash
brev search [flags]
brev search gpu [flags]
```

### GPU Flags

| Flag               | Short | Description                                                                      |
| ------------------ | ----- | -------------------------------------------------------------------------------- |
| `--gpu-name`       | `-g`  | Filter by GPU name (case-insensitive, partial match)                             |
| `--provider`       | `-p`  | Filter by cloud provider.                                                        |
| `--min-vram`       | `-v`  | Minimum VRAM per GPU (GB)                                                        |
| `--min-total-vram` | `-t`  | Minimum total VRAM across all GPUs (GB)                                          |
| `--min-capability` | `-c`  | Minimum GPU compute capability.                                                  |
| `--min-disk`       |       | Minimum disk size (GB)                                                           |
| `--max-boot-time`  |       | Maximum boot time (minutes)                                                      |
| `--stoppable`      |       | Only stoppable instances.                                                        |
| `--rebootable`     |       | Only rebootable instances.                                                       |
| `--flex-ports`     |       | Only instances with configurable firewall.                                       |
| `--sort`           | `-s`  | Sort by: `price`, `gpu-count`, `vram`, `total-vram`, `vcpu`, `disk`, `boot-time` |
| `--desc`           | `-d`  | Sort descending.                                                                 |
| `--json`           |       | Output as JSON.                                                                  |
| `--wide`           | `-w`  | Show extra columns (RAM, ARCH)                                                   |

### GPU Examples

```bash
# List all available GPUs (sorted by price)
brev search

# Wide mode with extra columns
brev search gpu --wide

# Filter by GPU model
brev search --gpu-name A100
brev search --gpu-name H100

# Filter by VRAM
brev search --min-vram 40 --sort price

# Fast-booting GPUs
brev search --max-boot-time 3 --sort price

# Stoppable instances with minimum VRAM
brev search --stoppable --min-total-vram 40 --sort price
```

## CPU Search

Search for CPU-only instance types (no GPU).

```bash
brev search cpu [flags]
```

### CPU Flags

| Flag              | Short | Description                                                       |
| ----------------- | ----- | ----------------------------------------------------------------- |
| `--provider`      | `-p`  | Filter by cloud provider.                                         |
| `--arch`          |       | Filter by architecture (`x86_64`, `arm64`)                        |
| `--min-ram`       |       | Minimum RAM in GB.                                                |
| `--min-disk`      |       | Minimum disk size (GB)                                            |
| `--min-vcpu`      |       | Minimum number of vCPUs.                                          |
| `--max-boot-time` |       | Maximum boot time (minutes)                                       |
| `--stoppable`     |       | Only stoppable instances.                                         |
| `--rebootable`    |       | Only rebootable instances.                                        |
| `--flex-ports`    |       | Only instances with configurable firewall.                        |
| `--sort`          | `-s`  | Sort by: `price`, `vcpu`, `type`, `provider`, `disk`, `boot-time` |
| `--desc`          | `-d`  | Sort descending.                                                  |
| `--json`          |       | Output as JSON.                                                   |

### CPU Examples

```bash
# All CPU instances
brev search cpu

# AWS CPU instances
brev search cpu --provider aws

# High-memory instances
brev search cpu --min-ram 64 --sort price

# ARM architecture
brev search cpu --arch arm64

# Many-core instances
brev search cpu --min-vcpu 16 --sort price

# Pipe to create
brev search cpu --min-ram 64 | brev create my-cpu-box
```

## Compute Capability Reference

GPU compute capability indicates the architecture generation. Use `--min-capability` to filter.

| Capability | Architecture | GPUs           |
| ---------- | ------------ | -------------- |
| 7.0        | Volta        | V100           |
| 7.5        | Turing       | T4, RTX 20xx   |
| 8.0        | Ampere       | A100, A10, A30 |
| 8.6        | Ampere       | RTX 30xx, A40  |
| 8.9        | Ada Lovelace | L40, RTX 40xx  |
| 9.0        | Hopper       | H100           |

```bash
# Ampere or newer
brev search --min-capability 8.0

# Hopper only
brev search --min-capability 9.0
```

## Output Formats

### Table Output (Default)

When run interactively, `brev search` displays a formatted table:

```
TYPE            GPU         COUNT  VRAM   TOTAL   $/HR   BOOT  FEATURES
g5.xlarge       A10G        1      24GB   24GB    $1.00  2m    S R P
g5.2xlarge      A10G        1      24GB   24GB    $1.20  2m    S R P
p4d.24xlarge    A100        8      40GB   320GB   $32.77 5m    S R
```

### Features Column

| Code  | Meaning                                         |
| ----- | ----------------------------------------------- |
| **S** | Stoppable — can stop/restart without data loss. |
| **R** | Rebootable — can reboot the instance.           |
| **P** | Flex Ports — can modify firewall rules.         |

### JSON Output

Use `--json` for structured output. Process results with `jq`:

```bash
brev search --json | jq '.[] | {type, gpu_name, price}'
```

### Piped Output

When stdout is piped to another command, `brev search` outputs instance type names only (one per line), enabling direct chaining with `brev create`:

```bash
brev search --gpu-name A100 | brev create my-instance
```

## Common Filter Recipes

### Development (Fast and Cheap)

```bash
brev search --max-boot-time 3 --sort price
```

### ML Training (High VRAM)

```bash
brev search --min-vram 40 --sort price
```

### Large Model Training

```bash
brev search --min-total-vram 80 --sort price
```

### Production (Fast and Reliable)

```bash
brev search --gpu-name A100 --max-boot-time 5 --sort price
```

### Budget Conscious

```bash
brev search --min-vram 16 --sort price | head -5
```

### Latest Architecture

```bash
brev search --min-capability 9.0 --sort price
```

# Composable Workflows

> Chain Brev CLI commands together using pipes, batch operations, and structured output for automation workflows.

Brev CLI commands are designed to compose together using standard Unix pipes. Commands read instance names from stdin and output instance names to stdout.

## Pipe Architecture

```mermaid
%%{init: {'themeVariables': {'fontFamily': 'monospace'}}}%%
flowchart LR
    A["<b>Discovery</b><br />brev search<br />brev ls<br />grep/awk"] --> B["<b>Lifecycle</b><br />brev create<br />brev stop<br />brev start<br />brev delete"]
    B --> C["<b>Access</b><br />brev open<br />brev exec<br />brev shell<br />brev delete"]
    style A text-align:left
    style B text-align:left
    style C text-align:left
```

**Sources** produce instance names (one per line). **Actions** read names from stdin, perform operations, and output names to stdout for further chaining.

## Output Modes

Commands automatically detect whether their output is going to a terminal or a pipe:

| Mode                       | Behavior                                 | Example                |
| -------------------------- | ---------------------------------------- | ---------------------- |
| **Interactive** (terminal) | Formatted table with headers and colors. | `brev ls`              |
| **Piped** (stdout)         | Instance names only, one per line.       | `brev ls \| brev stop` |
| **JSON** (`--json`)        | Structured JSON output.                  | `brev ls --json`       |

## Piping from `brev ls`

Use `awk` and `grep` to extract instance names from `brev ls` output:

```bash
# Stop all running instances
brev ls | awk '/RUNNING/ {print $1}' | brev stop

# Delete all stopped instances
brev ls | awk '/STOPPED/ {print $1}' | brev delete

# Start all stopped instances
brev ls | awk '/STOPPED/ {print $1}' | brev start

# Open all running instances in Cursor
brev ls | awk '/RUNNING/ {print $1}' | brev open cursor

# Run nvidia-smi on all running instances
brev ls | awk '/RUNNING/ {print $1}' | brev exec "nvidia-smi"
```

### Filtering with grep

```bash
# Stop instances matching a pattern
brev ls | grep "test-" | awk '{print $1}' | brev stop

# Delete old experiment instances
brev ls | grep "experiment" | awk '{print $1}' | brev delete

# Open all "dev-" instances
brev ls | grep "^dev-" | awk '{print $1}' | brev open
```

## Create-to-Access Chains

Chain `brev search`, `brev create`, and access commands into single pipelines:

```bash
# Search, create, and open
brev search --gpu-name A100 | brev create my-box | brev open cursor

# Create and run a command
brev create my-box | brev exec "nvidia-smi"

# Create and run a setup script
brev create my-box | brev exec @setup.sh

# Create cluster and verify all nodes
brev create my-cluster --count 3 | brev exec "hostname && nvidia-smi"
```

## Batch Operations

Several commands accept multiple instance names as arguments:

```bash
# Stop multiple instances
brev stop instance1 instance2 instance3

# Delete multiple instances
brev delete instance1 instance2 instance3

# Start multiple instances
brev start instance1 instance2

# Run on multiple instances
brev exec instance1 instance2 instance3 "nvidia-smi"
```

### The `--all` Flag

`brev stop` supports `--all` to stop every running instance:

```bash
brev stop --all
```

### Exit Codes for Batch Operations

When operating on multiple instances, commands return exit code **2** if some (but not all) operations fail. This lets you distinguish between full success, partial failure, and total failure in scripts.

## Safety: Preview Before Destructive Operations

Always preview what a pipeline will affect before running destructive operations:

```bash
# Preview what will be stopped
brev ls | awk '/RUNNING/ {print $1}'

# Then actually stop
brev ls | awk '/RUNNING/ {print $1}' | brev stop
```

Pipe the output without the final destructive command first to verify the instance list. Then add `| brev stop` or `| brev delete` when you're satisfied.

## JSON Processing with jq

Use `--json` output with `jq` for advanced filtering and data extraction:

```bash
# Get instance names and statuses
brev ls --json | jq '.[] | {name, status}'

# Search results as JSON
brev search --json | jq '.[] | {type, gpu_name, price}'

# Filter search results programmatically
brev search --json | jq '[.[] | select(.price < 2.0)]'
```

## Real-World Recipes

### ML Training Setup

```bash
# Find a cheap A100, create with setup script, and open
brev search --gpu-name A100 --sort price \
  | brev create training-box \
  | brev exec @setup.sh \
  | brev open cursor
```

### Instance Cleanup

```bash
# Preview stopped instances
brev ls | awk '/STOPPED/ {print $1}'

# Delete all stopped instances
brev ls | awk '/STOPPED/ {print $1}' | brev delete

# Stop and delete all test instances
brev ls | grep "test-" | awk '{print $1}' | brev delete
```

### Quick Dev Session

```bash
# One-liner: create and open in Cursor
brev create dev-box | brev open cursor
```

### Multi-Node Cluster

```bash
# Create 3 nodes, install deps on all, verify
brev create my-cluster --count 3 --type g5.xlarge \
  | brev exec @install-deps.sh \
  | brev exec "nvidia-smi"
```

# Advanced Commands

> Organization management, SSH keys, and advanced CLI operations for NVIDIA Brev.

Manage organizations, SSH keys, and perform advanced operations with the Brev CLI.

## Organization Management

### brev set

Switch your active organization context. All subsequent commands will operate within this organization.

```bash
# List available organizations
brev set

# Switch to a specific organization
brev set my-org
```

### brev login

Authenticate with Brev. Opens a browser window for login.

```bash
brev login
```

If you're already logged in, `brev login` will refresh your credentials without requiring re-authentication.

### brev logout

Clear your local authentication credentials.

```bash
brev logout
```

## SSH Key Management

Manage SSH keys for accessing your instances.

### brev ssh-key

View and manage your SSH keys.

```bash
# List your SSH keys
brev ssh-key

# Add a new SSH key from file
brev ssh-key add ~/.ssh/id_rsa.pub
```

Brev automatically manages an SSH key at `~/.brev/brev.pem`. You can add additional keys for team members or CI/CD systems.

## Instance Operations

### brev scale

Scale your instance to different GPU configurations.

```bash
# Scale to a different GPU type
brev scale my-instance --gpu A100

# Scale to multiple GPUs
brev scale my-instance --gpu-count 2
```

| Flag          | Description          |
| ------------- | -------------------- |
| `--gpu`       | GPU type to scale to |
| `--gpu-count` | Number of GPUs       |

Scaling requires stopping and restarting the instance. Your data persists, but running processes will be interrupted.

### brev reset

Reset an instance to its initial state. This clears the container while preserving your persistent storage.

```bash
brev reset my-instance
```

Use this when:

* Your container environment becomes corrupted
* You want to start fresh with a new container image
* You need to clear installed packages and return to the base environment

### brev refresh

Sync your local SSH configuration with the latest instance data.

```bash
brev refresh
```

This command updates `~/.brev/ssh_config` with current instance IP addresses and hostnames. Run this after:

* Creating a new instance
* Restarting an instance (IP may change)
* If SSH connections fail with "host not found"

## What's Next

Connect to instances via SSH, VS Code, and port forwarding.

Create, start, stop, and delete GPU instances.

# Guides

> Step-by-step guides for common NVIDIA Brev workflows - console, VS Code, Jupyter, Docker, and NVIDIA NIMs.

Step-by-step tutorials for common workflows on NVIDIA Brev.

**Beginner** - Navigate the web console to create instances, manage teams, and configure billing.

**Beginner** - Configure VS Code to develop directly on your GPU instance with full IDE features.

**Beginner** - Access JupyterLab on your GPU instance with port forwarding for interactive development.

**Beginner** - Transfer files between your local machine and GPU instances using SCP.

**Intermediate** - Run Docker and Docker Compose workloads with GPU access on your Brev instance.

**Advanced** - Run optimized NVIDIA inference microservices for production-ready AI inference.

**Reference** - Everything you need to know about NVIDIA GPU Cloud - containers, models, Helm charts, and CLI.

# Console Reference

> Navigate the NVIDIA Brev web console to manage GPU instances and teams.

The NVIDIA Brev console at [brev.nvidia.com](https://brev.nvidia.com) provides a web interface for managing your GPU resources and team.

## Navigation Overview

The console sidebar organizes features into these main sections:

| Section         | Purpose                                                              |
| --------------- | -------------------------------------------------------------------- |
| **GPUs**        | Create and manage GPU instances.                                     |
| **Blueprints**  | Preconfigured environments for common workflows.                     |
| **Launchables** | Quick-start templates for specific use cases.                        |
| **Team**        | Manage organization members and permissions.                         |
| **Billing**     | View usage, credits, invoices, resource limits, and payment methods. |

## GPU Instances

The GPUs section displays all instances in your organization.

### Creating an Instance

From the GPUs page, click the **Create Instance** button.

Choose from available GPU types (L40S, A100, H100, etc.) based on your workload needs.

* Enter an instance name
* Select a base image or Launchable
* Choose disk size
* Optionally configure environment variables

Click **Create** to provision your instance. Setup typically takes 1-2 minutes.

### Instance Details

Click any instance to view its details page with:

* **Status**: Current state (Running, Stopped, Starting, etc.)
* **GPU**: Type and count of attached GPUs
* **Uptime**: How long the instance has been running
* **Disk Usage**: Current storage utilization

### Access Tab

The Access tab provides connection information:

**SSH Connection**

* Instance hostname for direct SSH access
* Command to copy: `ssh <instance-name>`

**Using Tunnels**
Expose ports with publicly accessible URLs:

1. Enter a port number (e.g., 8888 for Jupyter)
2. Click **Add**
3. Copy the generated URL

Tunnels route through Cloudflare and require browser authentication on first access. For direct API access without browser redirects, use `brev port-forward` from the CLI instead.

**Port Exposure**
View and manage which ports are exposed on your instance.

## Blueprints & Launchables

### Blueprints

Blueprints are preconfigured environment templates that include:

* Base container image
* Preinstalled packages and dependencies
* Environment configuration

Common blueprints include PyTorch, TensorFlow, and RAPIDS environments.

### Launchables

Launchables are quick-start templates for specific use cases:

* **JupyterLab**: Ready-to-use notebook environment
* **VS Code Server**: Browser-based VS Code
* **LLM Fine-tuning**: Preconfigured for model training

Select a Launchable when creating an instance to start with everything preconfigured.

## Team Management

Manage your organization's members and permissions.

### Inviting Members

Click **Team** in the sidebar.

Click the **Invite Member** button.

Enter the email address of the person to invite.

Choose their role:

* **Member**: Can create and manage their own instances
* **Admin**: Full organization management access

### Managing Members

From the Team page you can:

* View all organization members
* Change member roles
* Remove members from the organization

## Billing & Usage

Use the Billing page to track costs, manage credits, review payment history, and understand how quickly your organization is using its balance.

### Usage Dashboard

The Usage Dashboard shows usage for the selected date range. It defaults to the current month.

View:

* Compute and storage costs over time
* Usage grouped by user or instance
* Total cost for the selected date range

Stopped instances do not accrue compute charges, but storage charges may still apply while Brev preserves the instance data. Delete unused instances to stop all charges for that instance.

### Credits and Auto Recharge

Your credit balance is shared across the organization. Running instances consume credits for compute and may also consume credits for storage. The balance indicator in the console shows your current balance and, when resources are running, an estimated burn rate and remaining hours.

Use the Credits section to:

* Add funds
* Redeem a credit code
* Enable or disable auto recharge
* Set the balance threshold that triggers auto recharge
* Set the amount to add when auto recharge runs

Auto recharge helps prevent interrupted work. When your balance falls below your configured threshold, Brev attempts to add funds using your saved payment method.

If auto recharge succeeds, your credits are updated automatically. If auto recharge fails, Brev emails the billing contact and stops attempting auto recharge until billing is updated.

### Running Out of Credits

If your organization runs out of credits, Brev sends a warning email and pauses any instances that have stop-start ability. Instances that cannot be paused are deleted.

If credits are not added, Brev sends another warning after 24 hours. If the organization remains out of credits, Brev deletes all remaining resources.

Deleted instances and their data cannot be recovered. Add credits or enable auto recharge before your balance reaches zero, and regularly push important work to Git or another durable storage location.

### Resource Limits

Resource limits are separate from credits. Your organization may have a maximum allowed resource usage rate, shown in dollars per hour. If you need to run larger or more expensive workloads, contact [brev-support@nvidia.com](mailto:brev-support@nvidia.com) to request a higher limit.

### Payment Methods

Add and manage credit cards used for credit purchases and auto recharge. Keep a valid payment method on file if you want auto recharge to protect running workloads.

### Invoices

Review payment history and download available invoices for accounting and reimbursement.

## What's Next

Create your first GPU instance in minutes.

Manage resources from the command line.

# VS Code Remote SSH Setup

> Configure VS Code Remote SSH to develop on your NVIDIA Brev GPU instance.

Configure VS Code to develop directly on your GPU instance with full IDE features, including IntelliSense, debugging, and extensions.

## Prerequisites

* VS Code installed locally
* Brev CLI installed and logged in
* A running Brev instance

## Quick Method: brev open

The fastest way to open VS Code on your instance:

```bash
brev open my-instance
```

This command automatically installs the Remote SSH extension if needed and opens your instance in VS Code.

## Manual Setup

Install the [Remote - SSH extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) from the VS Code marketplace.

Ensure your SSH config is up to date:

```bash
brev refresh
```

1. Open VS Code Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`)
2. Type "Remote-SSH: Connect to Host"
3. Select your instance name from the list
4. Wait for VS Code to set up the remote connection

## Recommended Extensions

Install these extensions on your remote instance for the best experience:

* **Python** - IntelliSense, linting, debugging
* **Jupyter** - Run notebooks inside VS Code
* **GitLens** - Enhanced Git integration

## What's Next

Run JupyterLab with GPU acceleration.

Run Docker workloads with GPU access.

# Running Jupyter Notebooks

> Run JupyterLab on your NVIDIA Brev GPU instance with port forwarding.

Access JupyterLab on your GPU instance with port forwarding for interactive development with GPU acceleration.

## Start JupyterLab

Connect to your instance and start JupyterLab:

```bash
# Connect to your instance
brev shell my-instance

# Start JupyterLab (no browser on remote)
jupyter lab --no-browser --port=8888
```

Copy the URL with token from the output (looks like `http://localhost:8888/lab?token=...`).

## Forward the Port

In a new terminal window on your local machine:

```bash
brev port-forward my-instance --port 8888:8888
```

Now open the Jupyter URL (with token) in your local browser: `http://localhost:8888`

## Verify GPU Access

In a notebook cell, verify the GPU is available:

```python
import torch
print(f"CUDA available: {torch.cuda.is_available()}")
print(f"GPU: {torch.cuda.get_device_name(0)}")
```

## Best Practices

* Use `jupyter lab --ip 0.0.0.0` if you need to access from external hosts
* Run Jupyter in a `tmux` session to keep it running after disconnecting
* Forward TensorBoard on port 6006 alongside Jupyter for experiment tracking

## What's Next

Run Docker workloads with GPU access.

Access NVIDIA's GPU-optimized containers and models.

# Custom Docker Containers

> Run Docker and Docker Compose workloads with GPU access on NVIDIA Brev.

Run Docker and Docker Compose workloads with GPU access on your Brev instance for reproducible, isolated development.

## Creating an Instance with Containers

You can configure containers when creating a new instance through the Brev console.

Click **+ New** in the Brev console to begin creating an instance.

Choose your runtime mode:

* **Container Mode**: Run a single Docker container
* **Docker Compose Mode**: Run multi-container applications
* **VM Mode**: If you don't need containers, use this for a plain GPU VM

Refer to the sections below for Container Mode and Docker Compose Mode configuration.

Choose whether to run a JupyterLab server on the instance. If your container provides its own Jupyter server, select **No** to avoid conflicts.

Choose your GPU type and click **Deploy**. The container builds on that GPU after provisioning.

### Container Mode Options

When you select Container Mode, choose from:

| Option                  | Description                                                                                               |
| ----------------------- | --------------------------------------------------------------------------------------------------------- |
| **Featured Containers** | Curated images for common AI/ML workloads. Use our default container for auto-configured Python and CUDA. |
| **Custom Container**    | Specify any container image. For private registries, provide credentials and an entrypoint command.       |

**Custom Container Caution**: Some custom containers may produce unexpected results if they modify host system configurations. Test thoroughly before production use.

### Docker Compose Mode Options

When you select Docker Compose Mode, provide your configuration through:

* **Upload**: Upload a local `docker-compose.yml` file
* **URL**: Provide a GitHub or GitLab URL pointing to a `docker-compose.yml` file

## Running Containers with GPU (CLI)

Brev instances have Docker and NVIDIA Container Toolkit preinstalled. Use the `--gpus all` flag to enable GPU access:

```bash
# Run PyTorch container with GPU
docker run --gpus all -it nvcr.io/nvidia/pytorch:24.01-py3 python -c "import torch; print(torch.cuda.is_available())"

# Run with port mapping
docker run --gpus all -p 8888:8888 -it nvcr.io/nvidia/pytorch:24.01-py3
```

## Docker Compose with GPU

For multi-container applications, use Docker Compose with GPU support:

```yaml
# docker-compose.yml
services:
  app:
    image: nvcr.io/nvidia/pytorch:24.01-py3
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    ports:
      - "8888:8888"
    volumes:
      - ./:/workspace
```

```bash
# Start the stack
docker compose up -d

# View logs
docker compose logs -f
```

## NVIDIA NGC Images

NVIDIA provides optimized containers for common AI/ML frameworks:

| Framework  | Image                                                |
| ---------- | ---------------------------------------------------- |
| PyTorch    | `nvcr.io/nvidia/pytorch:24.01-py3`                   |
| TensorFlow | `nvcr.io/nvidia/tensorflow:24.01-tf2-py3`            |
| JAX        | `nvcr.io/nvidia/jax:24.01-py3`                       |
| RAPIDS     | `nvcr.io/nvidia/rapidsai/base:24.02-cuda12.0-py3.10` |

## What's Next

Access NVIDIA's GPU-optimized containers and models.

Deploy NVIDIA Inference Microservices.

# File Transfer with SCP

> Transfer files to and from GPU instances using SCP and the brev copy command.

Transfer files between your local machine and Brev GPU instances using SCP or the built-in `brev copy` command.

## Prerequisites

* Brev CLI installed and logged in
* A running Brev instance
* SSH config updated (`brev refresh`)

## Using brev copy

The `brev copy` command wraps SCP with automatic instance resolution.

Copy a local file to your instance:

```bash
brev copy ./local-file.txt my-instance:/home/ubuntu/
```

Copy a directory recursively:

```bash
brev copy -r ./my-project my-instance:/home/ubuntu/
```

Copy a file from your instance to local:

```bash
brev copy my-instance:/home/ubuntu/results.csv ./
```

Copy a directory:

```bash
brev copy -r my-instance:/home/ubuntu/outputs ./local-outputs
```

### brev copy Flags

| Flag     | Description                                         |
| -------- | --------------------------------------------------- |
| `-r`     | Recursive copy (for directories)                    |
| `--host` | Copy to/from the host machine instead of container. |

## Direct SCP Usage

You can also use SCP directly with the Brev-managed SSH key.

### Basic Syntax

```bash
# Upload to instance
scp -i ~/.brev/brev.pem ./file.txt ubuntu@<instance-ip>:/home/ubuntu/

# Download from instance
scp -i ~/.brev/brev.pem ubuntu@<instance-ip>:/home/ubuntu/file.txt ./

# Recursive directory copy
scp -r -i ~/.brev/brev.pem ./my-folder ubuntu@<instance-ip>:/home/ubuntu/
```

### Using Managed SSH Config

After running `brev refresh`, your SSH config is automatically configured. You can use instance names directly:

```bash
# Upload using instance name
scp ./file.txt my-instance:/home/ubuntu/

# Download using instance name
scp my-instance:/home/ubuntu/file.txt ./
```

Run `brev refresh` after creating or restarting instances to ensure your SSH config is up to date.

## Container vs Host Paths

Brev instances run a container on top of a host machine. Understanding the path mappings is important for file transfers.

| Target                | Path                      | Use Case                           |
| --------------------- | ------------------------- | ---------------------------------- |
| **Host machine**      | `/home/ubuntu/`           | Persistent storage, large datasets |
| **Default container** | `/home/ubuntu/workspace/` | Development files, code            |
| **Custom container**  | `/root/workspace/`        | Custom Docker images               |

### Default Setup

By default, `brev copy` targets the container. Files placed in `/home/ubuntu/workspace/` inside the container are persisted through restarts.

```bash
# Copy to container workspace (default)
brev copy ./code.py my-instance:/home/ubuntu/workspace/
```

### Copying to Host

Use the `--host` flag to copy directly to the host machine:

```bash
# Copy to host machine
brev copy --host ./large-dataset.tar.gz my-instance:/home/ubuntu/
```

**When to use host vs container:**

* **Host**: Large datasets, files that need to persist outside the container
* **Container**: Code and development files you're actively working on

### Custom Container Paths

If you're using a custom container image, the workspace may be mounted at a different path:

```bash
# For custom containers, workspace is typically at /root/
brev copy ./file.txt my-instance:/root/workspace/
```

Check your container's configuration for the exact mount point.

## Common Patterns

### Syncing Project Files

Upload your entire project:

```bash
brev copy -r ./my-ml-project my-instance:/home/ubuntu/workspace/
```

### Downloading Training Results

Retrieve model checkpoints and logs:

```bash
brev copy -r my-instance:/home/ubuntu/workspace/outputs ./local-outputs
```

### Transferring Large Datasets

For large files, copy to the host for better performance:

```bash
brev copy --host ./dataset.tar.gz my-instance:/home/ubuntu/data/
```

Then extract inside the instance:

```bash
brev shell my-instance
tar -xzf /home/ubuntu/data/dataset.tar.gz -C /home/ubuntu/workspace/
```

## Troubleshooting

**Permission denied**

Ensure you've run `brev refresh` and the instance is running:

```bash
brev refresh
brev ls  # Check instance status
```

**Connection refused**

The instance may still be starting. Wait for status to show "Running":

```bash
brev ls
```

**Slow transfers**

For large files, consider:

* Compressing before transfer (`tar -czf`)
* Using `rsync` for incremental syncs
* Transferring to host instead of container

## What's Next

Learn about SSH, port forwarding, and tunnels.

Run JupyterLab with GPU acceleration.

# Running Agents on Brev

> Deploy AI agents on NVIDIA Brev CPU instances for sandboxed code execution, web tasks, and more.

Deploy AI agents on Brev CPU instances for sandboxed execution environments. CPU instances provide isolated, cost-effective compute for agent workloads that don't require GPU acceleration.

## Prerequisites

* A Brev account ([sign up](https://brev.nvidia.com))
* Brev CLI installed ([Quickstart](/getting-started/quickstart))

## Deploy an Agent Sandbox

### Option A: Deploy from a Launchable

Use a pre-built Launchable to get started quickly:

* **NemoClaw Agent** — the NVIDIA agent framework for tool-use and code execution
* **Generic Agent Sandbox** — a blank CPU sandbox for custom agent deployments

Browse available Launchables at [brev.nvidia.com](https://brev.nvidia.com/environment/new/public). Select a CPU instance type and deploy.

### Option B: Provision Manually

Create a CPU instance through the [Brev Console](https://brev.nvidia.com) or CLI:

```bash
brev create my-agent
```

Select a CPU instance type (no GPU) when prompted, or specify one in the [Brev Console](https://brev.nvidia.com).

### Connect and Verify

After the instance is running, connect with the CLI:

```bash
brev shell my-agent
```

Check that your agent process is active:

```bash
# Check running processes
ps aux | grep agent

# Check Docker containers if using containerized agents
docker ps
```

## CPU vs GPU for Agents

| Use Case                    | Recommended  | Why                               |
| --------------------------- | ------------ | --------------------------------- |
| Code execution / sandboxes  | CPU instance | No GPU needed, lower cost.        |
| Web browsing / scraping     | CPU instance | Network-bound, not compute-bound. |
| Tool use / API calls        | CPU instance | Minimal compute requirements.     |
| LLM inference (self-hosted) | GPU instance | Models require GPU acceleration.  |
| Vision / image processing   | GPU instance | GPU accelerates image operations. |
| Training / fine-tuning      | GPU instance | Requires GPU compute.             |

## What's Next?

Create and share one-click deployable agent environments.

# Using the CLI with AI Agents

> Install the Brev CLI skill for AI coding agents like Claude Code and Codex to manage GPU instances with natural language.

The Brev CLI includes a skill that enables AI coding agents to manage GPU and CPU instances using natural language. After installation, use natural language such as "create an A100 instance for ML training" and your agent runs the appropriate `brev` commands.

## Supported Agents

The skill installs to the following agent platforms:

| Agent        | Install Path                 |
| ------------ | ---------------------------- |
| Claude Code  | `~/.claude/skills/brev-cli/` |
| Codex        | `~/.codex/skills/brev-cli/`  |
| Other agents | `~/.agents/skills/brev-cli/` |

## Installing the Skill

### Option 1: Using the CLI

```bash
brev agent-skill install
```

Or simply run `brev agent-skill` — it defaults to install.

### Option 2: One-Liner (curl)

```bash
curl -fsSL https://raw.githubusercontent.com/brevdev/brev-cli/main/scripts/install-agent-skill.sh | bash
```

### Option 3: Automatic Prompt

When you run `brev login` and the CLI detects an AI coding agent on your system, it offers to install the skill automatically.

## What Gets Installed

The skill installs the following files to each agent directory:

```
~/.claude/skills/brev-cli/
├── SKILL.md              # Skill definition and quick reference
├── prompts/
│   ├── quick-session.md  # Quick GPU session workflow
│   ├── ml-training.md    # ML training setup workflow
│   └── cleanup.md        # Instance cleanup workflow
├── reference/
│   ├── commands.md       # Full command reference
│   └── search-filters.md # GPU/CPU search filter details
└── examples/
    └── common-patterns.md # Common usage patterns
```

## Agent-Driven Workflows

After installation, restart your agent (or start a new conversation) and use natural language:

```
"Create an A100 instance for ML training"
"Search for GPUs with 40GB VRAM under $3/hr"
"Stop all my running instances"
"Open my-instance in Cursor"
"What GPUs are available with fast boot times?"
```

The agent translates these requests into the appropriate `brev` CLI commands, confirms before destructive operations, and shows costs before creating instances.

## Safety Rules

The skill instructs agents to follow these safety rules:

* **Always confirm** before deleting or stopping instances
* **Always show cost/type** before creating instances
* **Always confirm** before creating expensive instances (H100, multi-GPU) or clusters (`--count > 1`)
* **Always check** `brev ls` before assuming an instance exists

## Updating the Skill

Re-run the install command to update to the latest version:

```bash
brev agent-skill install
```

### Testing from a Branch

To test skill changes from a specific branch:

```bash title="Using CLI"
BREV_SKILL_BRANCH=my-branch brev agent-skill install
```

```bash title="Using curl"
curl -fsSL https://raw.githubusercontent.com/brevdev/brev-cli/main/scripts/install-agent-skill.sh | bash -s -- --branch my-branch
```

## Uninstalling the Skill

```bash
brev agent-skill uninstall
```

Or with curl:

```bash
curl -fsSL https://raw.githubusercontent.com/brevdev/brev-cli/main/scripts/install-agent-skill.sh | bash -s -- --uninstall
```

This removes the skill from all agent directories. Restart your agent to apply the change.

## Troubleshooting

### Agent doesn't recognize Brev commands

* Verify the skill is installed: check that `~/.claude/skills/brev-cli/SKILL.md` exists
* Restart the agent or start a new conversation
* Try invoking the skill explicitly with `/brev-cli` (in Claude Code)

### Skill install fails

* Check your internet connection (files are downloaded from GitHub)
* Try the curl installer as an alternative
* Verify you have write permissions to `~/.claude/` and `~/.agents/`

### Agent runs wrong commands

* Update to the latest skill: `brev agent-skill install`
* Check that you're running the latest Brev CLI: `brev --version`

# Deploying NVIDIA NIMs

> Deploy NVIDIA Inference Microservices (NIMs) on your Brev GPU instance.

Run optimized NVIDIA Inference Microservices (NIMs) for production-ready AI inference on your Brev instance.

## What are NIMs?

NVIDIA Inference Microservices (NIMs) are pre-built, optimized containers for running AI models with industry-standard APIs. They include:

* CUDA, TensorRT, TensorRT-LLM, and Triton Inference Server
* OpenAI-compatible API endpoints
* Preconfigured for production workloads

A NIM container provides an interactive API for blazing fast inference. Deploying a large language model NIM requires the NIM container (API, server, runtime) and the model engine.

## Prerequisites

* NVIDIA NGC API key (get one at [ngc.nvidia.com](https://ngc.nvidia.com))
* GPU with sufficient VRAM—see the [NIM support matrix](https://docs.nvidia.com/nim/large-language-models/latest/support-matrix.html) for requirements
* Recommended: L40S 48GB or A100 80GB GPU

## Setting Up Your Instance

In the Brev console, create a new instance:

* Select **VM Mode** (not container mode)
* Choose an appropriate GPU (L40S or A100 recommended)
* Click **Deploy**

```bash
brev shell my-instance
```

```bash
docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi
```

## NGC Authentication

```bash
export NGC_CLI_API_KEY=<your-ngc-api-key>
```

Add to your shell profile so it's available on restart:

```bash
# For bash
echo "export NGC_CLI_API_KEY=<your-ngc-api-key>" >> ~/.bashrc

# For zsh
echo "export NGC_CLI_API_KEY=<your-ngc-api-key>" >> ~/.zshrc
```

```bash
echo "$NGC_CLI_API_KEY" | docker login nvcr.io --username '$oauthtoken' --password-stdin
```

## Using the NGC CLI (Optional)

The NGC CLI provides additional functionality for browsing and managing NIMs.

```bash
# Install NGC CLI
pip install ngc-cli

# Configure with your API key
ngc config set

# List available NIMs
ngc registry image list --format_type csv nvcr.io/nim/meta/*
```

Refer to the [NGC CLI documentation](https://docs.ngc.nvidia.com/cli/index.html) for more details.

## Deploying a NIM

This example deploys the Llama 3 8B Instruct NIM. The same pattern applies to other NIMs.

```bash
# Container name for bookkeeping
export CONTAINER_NAME=Llama3-8B-Instruct

# NIM image (check NGC for latest versions)
export IMG_NAME="nvcr.io/nim/meta/llama3-8b-instruct:1.0"

# Local cache for downloaded models
export LOCAL_NIM_CACHE=~/.cache/nim
mkdir -p "$LOCAL_NIM_CACHE"
```

```bash
docker run -it --rm --name=$CONTAINER_NAME \
  --runtime=nvidia \
  --gpus all \
  --shm-size=16GB \
  -e NGC_CLI_API_KEY \
  -v "$LOCAL_NIM_CACHE:/opt/nim/.cache" \
  -u $(id -u) \
  -p 8000:8000 \
  $IMG_NAME
```

The first run downloads the model weights, which may take several minutes depending on model size. Subsequent runs use the cached weights.

In a new terminal (or use `curl` from another machine):

```bash
curl -X POST 'http://localhost:8000/v1/completions' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "meta-llama3-8b-instruct",
    "prompt": "Once upon a time",
    "max_tokens": 225
  }'
```

## Exposing Your NIM Endpoint

NIMs expose port 8000 by default. To make your NIM accessible externally:

### Option 1: Port Forwarding (Recommended for API Access)

Use port forwarding for direct API access without authentication:

```bash
# From your local machine
brev port-forward my-instance --port 8000:8000

# Access at localhost:8000
curl -X POST http://localhost:8000/v1/chat/completions ...
```

### Option 2: Cloudflare Tunnels (Web Console)

Expose through the web console for shareable URLs:

1. Go to your instance details in the Brev console
2. In the **Access** section, find **Using Tunnels**
3. Add port 8000 to create a public URL

**Cloudflare Authentication**: Tunnel URLs route through Cloudflare and require browser authentication on first access. For direct API access (e.g., from scripts or other services), use port forwarding instead.

## API Endpoints

NIMs provide several OpenAI-compatible endpoints:

| Endpoint               | Description           |
| ---------------------- | --------------------- |
| `/v1/completions`      | Text completion       |
| `/v1/chat/completions` | Chat completion       |
| `/v1/models`           | List available models |
| `/v1/health/ready`     | Health check          |
| `/v1/metrics`          | Prometheus metrics    |

## Available NIMs

Explore the full catalog at [build.nvidia.com](https://build.nvidia.com). Popular NIMs include:

* **LLMs**: Llama 3.1, Mistral, Mixtral, Nemotron
* **Vision**: SegFormer, CLIP
* **Speech**: Whisper, RIVA
* **Embedding**: NV-Embed

## Troubleshooting

**Permission errors**: If you encounter permission issues, try running with `sudo`:

```bash
sudo docker run -it --rm --name=$CONTAINER_NAME ...
```

**Out of memory**: Ensure your GPU has sufficient VRAM for the model. Check the [NIM support matrix](https://docs.nvidia.com/nim/large-language-models/latest/support-matrix.html) for requirements.

# NGC Developer Guide

> Everything you need to know about NVIDIA GPU Cloud (NGC) - the hub for GPU-optimized AI software.

NGC is NVIDIA's hub for GPU-optimized AI software, serving as a GPU-optimized container registry for GPU-accelerated containers, pre-trained models, and AI toolkits specifically optimized for NVIDIA hardware.

Every asset in NGC is tested for security and validated across different GPUs for performance and scalability. This isn't just a repository - it's a curated, enterprise-grade catalog.

## What's in the NGC Catalog?

| Asset Type             | What You Get                  | Example Use Case                  |
| ---------------------- | ----------------------------- | --------------------------------- |
| **Containers**         | GPU-optimized Docker images   | PyTorch, TensorFlow, RAPIDS       |
| **Pre-trained Models** | Ready-to-deploy AI models     | NeMo LLMs, computer vision models |
| **Helm Charts**        | Kubernetes deployment configs | Deploy inference services on K8s  |
| **Resources**          | Datasets, Jupyter notebooks   | Training data, example workflows  |
| **SDKs**               | Domain-specific toolkits      | Healthcare, autonomous vehicles   |
| **Collections**        | Curated bundles               | End-to-end AI pipelines           |

Browse the catalog at [catalog.ngc.nvidia.com](https://catalog.ngc.nvidia.com/).

## Quick Start

Go to [ngc.nvidia.com](https://ngc.nvidia.com) and sign up with your NVIDIA account (or corporate SSO).

In the NGC web UI:

1. Click your profile → Setup
2. Generate API Key
3. Save it securely - you'll only see it once!

```bash
# Using pip (recommended)
pip install ngc-cli

# Or download directly
wget -O ngc https://api.ngc.nvidia.com/v2/resources/nvidia/ngc-apps/ngc_cli/versions/3.31.0/files/ngccli_linux.zip
unzip ngccli_linux.zip
chmod +x ngc-cli/ngc
export PATH=$PATH:$(pwd)/ngc-cli
```

```bash
# Interactive setup
ngc config set

# Or set environment variables
export NGC_API_KEY=<your-api-key>
export NGC_ORG=<your-org>  # Optional: for enterprise users
```

```bash
# Pull PyTorch container optimized for GPUs
docker pull nvcr.io/nvidia/pytorch:24.01-py3

# Run it
docker run --gpus all -it nvcr.io/nvidia/pytorch:24.01-py3
```

## Core Developer Workflows

### Pulling Containers

```bash
# Format: nvcr.io/<organization>/<repository>:<tag>

# NVIDIA's public containers
docker pull nvcr.io/nvidia/pytorch:24.01-py3
docker pull nvcr.io/nvidia/tensorflow:24.01-tf2-py3
docker pull nvcr.io/nvidia/tritonserver:24.01-py3

# Partner containers (ISV)
docker pull nvcr.io/isv-ngc-partner/company/container:version
```

### Downloading Models

```bash
# List available models
ngc registry model list

# Download a specific model
ngc registry model download-version nvidia/nemo/megatron_gpt_345m:1.0

# Download to specific directory
ngc registry model download-version nvidia/nemo/megatron_gpt_345m:1.0 --dest ./models/
```

### Using Resources (Datasets, Notebooks)

```bash
# List resources
ngc registry resource list

# Download a resource
ngc registry resource download-version nvidia/tao/tao_getting_started:1.0
```

### Working with Helm Charts

```bash
# Add NGC Helm repo
helm repo add nvidia https://helm.ngc.nvidia.com/nvidia

# Search for charts
helm search repo nvidia

# Install a chart (e.g., GPU Operator)
helm install gpu-operator nvidia/gpu-operator \
  --set driver.enabled=true \
  --namespace gpu-operator \
  --create-namespace
```

## NGC CLI Power Commands

```bash
# Search the catalog
ngc registry image list --format_type csv | grep pytorch

# Get detailed info about an image
ngc registry image info nvidia/pytorch:24.01-py3

# List all versions of a model
ngc registry model list --org nvidia --name nemo

# Check your orgs and teams
ngc org list
ngc team list

# Upload to private registry (enterprise)
ngc registry image push my-org/my-team/my-container:v1.0

# Scripting: JSON output for automation
ngc registry image list --format_type json | jq '.[] | .name'
```

## Registry Architecture

```mermaid
%%{init: {'themeVariables': {'fontFamily': 'monospace'}}}%%
flowchart LR
    A["nvcr.io<br />(pull/push)"] --> B["Reverse Proxy<br />(auth/authz)"]
    B --> C["Registry Server<br />(Docker API)"]
    D["layers.nvcr.io"] --> E["Container Blobs (US)"]
    F["ngc.download.nvidia.com"] --> G["Container Blobs (Global)"]
    H["authn.nvidia.com"] --> I["Authentication Service"]
    style A text-align:left
    style B text-align:left
    style C text-align:left
    style D text-align:left
    style E text-align:left
    style F text-align:left
    style G text-align:left
    style H text-align:left
    style I text-align:left
```

**Key URLs:**

* **nvcr.io** - Main registry for pulling containers
* **catalog.ngc.nvidia.com** - Web UI for browsing
* **api.ngc.nvidia.com** - REST API endpoint

## Deployment Options

| Environment    | How to Use NGC                                              |
| -------------- | ----------------------------------------------------------- |
| **Local/DGX**  | Direct `docker pull nvcr.io/...`                            |
| **AWS**        | NGC containers on EC2 GPU instances, SageMaker integration. |
| **GCP**        | NGC containers on Compute Engine with GPUs.                 |
| **Azure**      | NGC containers on Azure VMs with NVIDIA GPUs.               |
| **Kubernetes** | NGC Helm charts, GPU Operator.                              |
| **Edge**       | NGC containers optimized for Jetson.                        |

## Private Registry (Enterprise)

For enterprise users, NGC offers private registries to host your own containers and models:

```bash
# Push to private registry
docker tag my-container:latest nvcr.io/my-org/my-team/my-container:v1.0
docker push nvcr.io/my-org/my-team/my-container:v1.0

# Manage access
ngc org user add --org my-org --email colleague@company.com --role REGISTRY_USER
```

**Roles:**

* `REGISTRY_USER` - Can pull from private registry
* `REGISTRY_READ` - Read-only access
* `ADMIN` - Full management access

## Integration with NVIDIA Tools

| Tool                        | NGC Integration                           |
| --------------------------- | ----------------------------------------- |
| **NVIDIA AI Workbench**     | Pull models/containers directly from NGC. |
| **NeMo**                    | Pre-trained LLMs hosted on NGC.           |
| **Triton Inference Server** | Container and model hosting.              |
| **TAO Toolkit**             | Pre-trained vision models.                |
| **RAPIDS**                  | GPU-accelerated data science containers.  |
| **DeepStream**              | Video analytics containers.               |

## Best Practices

NVIDIA updates containers monthly. Use specific tags (`:24.01-py3`) in production, not `:latest`.

All NGC containers pass security scanning. Check the "Security" tab in the catalog for CVE reports.

Download containers and models to a local registry for air-gapped deployments.

Use NGC CLI in pipelines:

```bash
ngc registry image pull nvidia/pytorch:24.01-py3 --format_type json
```

NGC containers are optimized for multi-GPU setups out of the box.

## Essential Links

| Resource                | URL                                                                                               |
| ----------------------- | ------------------------------------------------------------------------------------------------- |
| NGC Catalog             | [catalog.ngc.nvidia.com](https://catalog.ngc.nvidia.com/)                                         |
| NGC Documentation       | [docs.nvidia.com/ngc](https://docs.nvidia.com/ngc/)                                               |
| NGC CLI Docs            | [docs.ngc.nvidia.com/cli](https://docs.ngc.nvidia.com/cli/)                                       |
| NGC User Guide          | [NGC User Guide](https://docs.nvidia.com/ngc/latest/ngc-user-guide.html)                          |
| Public Cloud Deployment | [NGC Deploy Guide](https://docs.nvidia.com/ngc/ngc-deploy-public-cloud/)                          |
| Private Registry Guide  | [Private Registry Guide](https://docs.nvidia.com/ngc/latest/ngc-private-registry-user-guide.html) |

## Summary

**NGC = GPU-optimized container registry + model hub + Helm charts**

```bash
# Get started in 3 commands:
pip install ngc-cli
ngc config set  # Enter your API key
docker pull nvcr.io/nvidia/pytorch:24.01-py3
```

You're ready to start building.

# Register Your DGX Spark

> Step-by-step guide to register your NVIDIA DGX Spark with Brev for SSH access, team sharing, and port forwarding.

Register your NVIDIA DGX Spark with Brev to enable SSH access, share it with your team, and forward ports — all through the Brev CLI.

## Prerequisites

* An NVIDIA DGX Spark running Linux
* A Brev account ([sign up at brev.nvidia.com](https://brev.nvidia.com))
* `sudo` access on the DGX Spark

## Registration

Install the Brev CLI on your DGX Spark:

```bash
curl -fsSL https://brev.nvidia.com/install | bash
```

Authenticate with your Brev account:

```bash
brev login
```

Register the machine with a descriptive name:

```bash
brev register "My DGX Spark"
```

This command performs three steps:

1. **Installs NetBird** — A mesh VPN agent for secure connectivity
2. **Profiles hardware** — Detects your GPU, CPU, RAM, storage, and interconnects
3. **Registers with Brev** — Makes the machine visible in your organization

This requires `sudo` access. NetBird is installed as a systemd service.

Enable SSH so you and your team can connect:

```bash
brev enable-ssh
```

When prompted, enter the SSH port (default is `22`).

Your DGX Spark is now registered and accessible through Brev.

## Connecting to Your DGX Spark

From any machine with the Brev CLI installed:

```bash
brev shell my-dgx-spark
```

## Sharing with Your Team

Grant SSH access to a teammate:

```bash
brev grant-ssh
```

This opens an interactive selector where you choose the org member to grant access. Once granted, they can connect with `brev shell my-dgx-spark` from their own machine.

To revoke access later:

```bash
brev revoke-ssh
```

## Port Forwarding

Forward ports from your DGX Spark to your local machine:

```bash
# Forward Jupyter
brev port-forward my-dgx-spark --port 8888:8888

# Forward multiple ports
brev port-forward my-dgx-spark --port 8888:8888 --port 6006:6006
```

Then open `http://localhost:8888` in your browser.

## Next Steps

* [Managing Registered Compute](/guides/registered-compute/managing-registered-compute) — Detailed guide on sharing, port forwarding, and deregistering
* [CLI Reference](/cli/registered-compute) — Full command reference for registered compute

# Register Your DGX Station

> Register your NVIDIA DGX Station with Brev for SSH access, team sharing, and port forwarding with multi-GPU support.

Register your NVIDIA DGX Station with Brev to enable SSH access, share it with your team, and forward ports. The registration process is the same as other hardware — Brev automatically detects your multi-GPU configuration and NVLink topology.

## Prerequisites

* An NVIDIA DGX Station running Linux
* A Brev account ([sign up at brev.nvidia.com](https://brev.nvidia.com))
* `sudo` access on the DGX Station

## Registration

```bash
curl -fsSL https://brev.nvidia.com/install | bash
```

```bash
brev login
```

```bash
brev register "My DGX Station"
```

Brev auto-detects your DGX Station's hardware profile including:

* Multiple GPUs and their memory
* NVLink interconnect topology
* CPU, RAM, and storage

This requires `sudo` access. NetBird is installed as a systemd service for secure mesh connectivity.

```bash
brev enable-ssh
```

Enter the SSH port when prompted (default: `22`).

Your DGX Station is now registered with its full hardware profile visible in Brev.

## Connecting and Sharing

The workflow is identical to other registered compute. See the [DGX Spark guide](/guides/registered-compute/register-dgx-spark) for detailed instructions on:

* **Connecting** with `brev shell`
* **Sharing** with `brev grant-ssh` and `brev revoke-ssh`
* **Port forwarding** with `brev port-forward`

## Next Steps

* [Managing Registered Compute](/guides/registered-compute/managing-registered-compute) — Sharing, port forwarding, and deregistering
* [CLI Reference](/cli/registered-compute) — Full command reference

# Managing Registered Compute

> Share access, forward ports, view device details, and deregister machines from NVIDIA Brev.

Once your machine is registered with Brev, you can share it with teammates, forward ports, and manage its lifecycle.

## Viewing Registered Compute

Registered machines appear in the Brev console alongside cloud GPU instances. You can view each machine's hardware profile, connection status, and authorized users.

## Sharing Access

### Granting SSH Access

Run this command **on the registered machine** to grant SSH access to a teammate:

```bash
brev grant-ssh
```

An interactive selector shows all members of your organization (excluding yourself). Select the user to grant access and enter the SSH port. Once granted, they can connect from their own machine:

```bash
brev shell <machine-name>
```

As a security measure, `brev grant-ssh` removes `~/.brev/credentials.json` before granting access.

### Revoking SSH Access

To revoke a user's access, run this **on the registered machine**:

```bash
brev revoke-ssh
```

An interactive selector shows all Brev-managed SSH keys with a key preview and associated user. Select the key to revoke. This performs a two-stage revocation:

1. Removes the SSH key from the local machine
2. Sends an RPC to the Brev server to revoke server-side access

## Port Forwarding

Forward ports from the registered machine to your local machine using `brev port-forward`:

```bash
# Forward a single port
brev port-forward my-dgx-spark --port 8888:8888

# Forward multiple ports
brev port-forward my-dgx-spark --port 8888:8888 --port 6006:6006
```

### Supported Protocols

Port forwarding supports TCP and UDP. The protocol is specified via the `OpenPort` RPC:

| Protocol | Use Case                                |
| -------- | --------------------------------------- |
| TCP      | Web servers, Jupyter, TensorBoard, APIs |
| UDP      | Streaming, real-time applications       |

### Common Port Forwards

| Service       | Command            |
| ------------- | ------------------ |
| Jupyter       | `--port 8888:8888` |
| TensorBoard   | `--port 6006:6006` |
| Streamlit     | `--port 8501:8501` |
| Gradio        | `--port 7860:7860` |
| NIM Inference | `--port 8000:8000` |

## Deregistering a Machine

To fully remove a machine from Brev, run this **on the registered machine**:

```bash
brev deregister
```

This performs a complete cleanup:

1. Unregisters the machine from the Brev server
2. Removes all SSH keys
3. Uninstalls the NetBird VPN agent
4. Deletes the local registration file (`/etc/brev/device_registration.json`)

Deregistering removes all access. Teammates will no longer be able to connect to this machine through Brev. You can re-register at any time with `brev register`.

# Reference

> NVIDIA Brev reference documentation - GPU types and specifications.

Technical reference documentation for GPU types and specifications.

Complete catalog of available GPUs with specifications, VRAM, and recommended use cases.

# GPU Types

> Complete catalog of available GPUs on NVIDIA Brev with specifications and recommended use cases.

Complete catalog of available GPUs with specifications and recommended use cases.

## High Performance

Best for large model training and inference workloads.

| GPU                  | VRAM        | Architecture | Best for                                      |
| -------------------- | ----------- | ------------ | --------------------------------------------- |
| **NVIDIA B200**      | 192GB HBM3e | Blackwell    | Large-scale AI training, enterprise inference |
| **NVIDIA H200**      | 141GB HBM3e | Hopper       | Large LLM training, HPC, multi-GPU inference  |
| **NVIDIA H100**      | 96GB HBM3   | Hopper       | Large LLM training, multi-GPU inference       |
| **NVIDIA A100 80GB** | 80GB HBM2e  | Ampere       | LLM fine-tuning, large batch training         |

## Mid-Range

Great balance of performance and cost for most workloads.

| GPU                            | VRAM       | Architecture | Best for                              |
| ------------------------------ | ---------- | ------------ | ------------------------------------- |
| **NVIDIA L40S**                | 44GB GDDR6 | Ada Lovelace | Inference, fine-tuning, rendering     |
| **NVIDIA L40**                 | 48GB GDDR6 | Ada Lovelace | Inference, fine-tuning, rendering     |
| **NVIDIA L4**                  | 22GB GDDR6 | Ada Lovelace | Inference, video processing           |
| **NVIDIA RTX 6000 Ada**        | 48GB GDDR6 | Ada Lovelace | Visualization, rendering, inference   |
| **NVIDIA RTX 4000 Ada**        | 20GB GDDR6 | Ada Lovelace | Development, visualization            |
| **NVIDIA RTX PRO Server 6000** | 96GB GDDR6 | Ada Lovelace | Enterprise visualization, rendering   |
| **NVIDIA A10G**                | 22GB GDDR6 | Ampere       | Inference, video encoding             |
| **NVIDIA A16**                 | 16GB GDDR6 | Ampere       | Virtual workstations, inference       |
| **NVIDIA A6000**               | 48GB GDDR6 | Ampere       | Professional visualization, training  |
| **NVIDIA A5000**               | 24GB GDDR6 | Ampere       | Professional visualization, inference |
| **NVIDIA A4000**               | 16GB GDDR6 | Ampere       | Development, visualization            |
| **NVIDIA RTX 5090**            | 32GB GDDR6 | Blackwell    | Development, fine-tuning, inference   |

## Entry Level

Cost-effective options for development and small-scale inference.

| GPU             | VRAM       | Architecture | Best for                           |
| --------------- | ---------- | ------------ | ---------------------------------- |
| **NVIDIA T4**   | 16GB GDDR6 | Turing       | Development, small model inference |
| **NVIDIA V100** | 32GB GDDR6 | Volta        | Training, inference                |
| **NVIDIA P4**   | 8GB GDDR6  | Pascal       | Inference, transcoding             |

*Last updated: 2026-04-06T08:41:52Z*

## Choosing a GPU

* **Model size:** Ensure VRAM exceeds model parameters (7B params \~ 14GB for fp16)
* **Training vs inference:** Training needs more VRAM than inference
* **Batch size:** Larger batches require more VRAM but improve throughput

# Troubleshooting

> Diagnose and resolve common issues with NVIDIA Brev CLI, connectivity, GPU detection, and instance management.

Find solutions to common issues with NVIDIA Brev. Start with the quick-reference guide for frequently encountered problems, or navigate to detailed guides for specific scenarios.

Quick-reference solutions for CLI, connectivity, container, and GPU issues.

Resolve SSH key authentication failures on macOS systems.

Diagnose and resolve instances that fail to provision.

Fix GPU detection issues with PyTorch, CUDA, and Unsloth on H100 instances.

Configure VS Code Remote SSH to work with Cloudflare Tunnel on Windows.

Resolve silent installation failures on Linux systems.

## Getting Help

If you cannot resolve your issue using these guides, contact support at [brev-support@nvidia.com](mailto:brev-support@nvidia.com) with:

* Your instance name and ID
* The commands you ran
* Any error messages
* Output from `brev ls` and relevant logs

# Common Issues

> Quick-reference solutions for frequently encountered NVIDIA Brev CLI, connectivity, container, and GPU issues.

Quick-reference solutions for common issues. For detailed troubleshooting guides, see the [Troubleshooting Overview](/troubleshooting).

## CLI Issues

### SSH Connection Fails

**Symptom**: `ssh: connect to host ... port 22: Connection refused`

**Solutions**:

1. Verify the instance is running with `brev list`
2. If you recently restarted the instance, run `brev refresh` to update SSH config with the new IP
3. Check your network allows outbound SSH (port 22)

```bash
# Check instance status
brev list

# Update SSH config
brev refresh

# Try connecting again
brev shell my-instance
```

For persistent SSH authentication issues on macOS, see [CLI SSH Authentication (macOS)](/troubleshooting/cli-installation/cli-ssh-authentication-macos).

### Instance not appearing in CLI

Instances created in the web console need to be synced to your local CLI.

```bash
brev refresh
```

### Login Fails

**Symptom**: Browser authentication doesn't complete

**Solutions**:

1. Try `brev login --skip-browser` and manually open the URL
2. For headless environments, use `brev login --token`
3. Clear browser cookies for brev.nvidia.com

```bash
# Skip auto-opening browser
brev login --skip-browser

# Token-based login for headless/CI
brev login --token
```

### Authentication expired

If commands fail with auth errors, re-authenticate with the CLI.

```bash
brev logout && brev login
```

### Editor Won't Open

**Symptom**: `brev open` fails with "command not found"

**Solutions**:

1. Verify the editor is installed and in your PATH
2. For VS Code: ensure `code` command is available (install from Command Palette: "Shell Command: Install 'code' command in PATH")
3. For Cursor/Windsurf: check application settings for CLI installation

```bash
# Set a different default editor
brev open --set-default cursor
```

For VS Code connection issues on Windows/WSL, see [VS Code Connection (Windows/WSL)](/troubleshooting/ide-connectivity/vscode-windows-wsl).

### Reset Brev CLI

If instances are missing or the CLI is behaving unexpectedly, force a refresh:

```bash
brev refresh
```

This updates the SSH config and ensures the daemon is running.

For Linux CLI installation issues, see [CLI Installation (Linux)](/troubleshooting/cli-installation/cli-installation-linux).

## Connectivity Issues

### SSH connection refused after restart

Instance IP addresses may change after a restart. Run refresh to update your SSH config.

```bash
# Update SSH config with new IPs
brev refresh

# Then try connecting again
brev shell my-instance
```

### Port forward not working

**Symptom**: localhost:port returns "connection refused"

**Solutions**:

1. Verify the service is running on the instance: `brev shell my-instance` then check the port
2. Check the port mapping is correct (local:remote)
3. Ensure no local service is using the same port

```bash
# On the instance, check if service is listening
netstat -tlnp | grep 8888

# Forward with explicit port mapping
brev port-forward my-instance --port 8888:8888

# If local port is in use, map to different local port
brev port-forward my-instance --port 9999:8888
```

## Container and Docker Compose Issues

### Debugging container build failures

If your container or Docker Compose build is failing, check the logs:

```bash
# SSH into the host machine
brev shell my-instance --host

# Navigate to workspace and view logs
cd workspace
docker compose logs
```

### JupyterLab tunnel issues

If you can't access JupyterLab and verified your container is running correctly, check the Cloudflare tunnel:

```bash
# SSH into the host
brev shell my-instance --host

# Check if cloudflared is running
ps aux | grep cloudflared

# Check service status
sudo systemctl status cloudflared

# If not running, start it
sudo systemctl start cloudflared
```

If your container or Docker Compose is setting up its own JupyterLab server, ensure it doesn't conflict with the host JupyterLab tunnel.

### Docker socket permission denied

If you get "permission denied while trying to connect to the Docker daemon socket":

```bash
sudo chmod 666 /var/run/docker.sock
```

Then re-run your Docker command.

### Viewing startup logs

If something went wrong during instance setup (e.g., empty project folder, failed git clone), check the startup logs:

```bash
brev shell my-instance --host
sudo cat /var/log/brev-workspace.log
```

This shows the full initialization sequence, including SSH key setup and repository cloning.

## GPU Issues

### GPU not available in container

Ensure you're using the `--gpus all` flag when running Docker containers.

```bash
# Run with GPU access
docker run --gpus all -it your-image

# Verify GPU in container
nvidia-smi
```

### Verifying GPU setup

After launching an instance, verify the GPU is properly configured:

```bash
# Check NVIDIA driver and GPU visibility
docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi
```

### CUDA out of memory

Your model or batch size is too large for the GPU VRAM.

* Reduce batch size
* Use gradient checkpointing
* Use mixed precision (fp16/bf16)
* Upgrade to a GPU with more VRAM

For GPU detection issues with PyTorch and Unsloth on H100 instances, see [GPU Detection and PyTorch Setup](/troubleshooting/instances-gpus/gpu-detection-pytorch).

## Instance Issues

For instances stuck in "Waiting" state, see [Instance Stuck in Waiting State](/troubleshooting/instances-gpus/instance-stuck-in-waiting-state).

# CLI Installation (Linux)

> Resolve silent installation failures when installing the NVIDIA Brev CLI on Linux systems.

This guide helps you resolve issues when the Brev CLI installation command completes without output or errors, but the CLI is not installed.

**Platform**: Linux (reported on Ubuntu 22.04)

## Problem

When installing the Brev CLI on Linux using the one-line install command:

```bash
sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/brevdev/brev-cli/main/bin/install-latest.sh)"
```

The command completes without any output, logs, or error messages, and the Brev CLI is not installed.

## Prerequisites

* Linux system (tested on Ubuntu 22.04)
* `curl` installed and available in `$PATH`
* Ability to run commands with `sudo`
* Outbound network access to `raw.githubusercontent.com`

## Solution

Download and run the install script directly instead of piping through a nested shell.

### Download the install script

```bash
curl -fsSL https://raw.githubusercontent.com/brevdev/brev-cli/main/bin/install-latest.sh -o install-latest.sh
```

### Make the script executable

```bash
chmod +x install-latest.sh
```

### Run the script

```bash
./install-latest.sh
```

### Check for errors (optional)

If the installation appears to fail silently, capture the exit code:

```bash
echo $?
```

A non-zero exit code indicates an error occurred.

## Verification

After running the installation script:

```bash
# Verify the binary exists
ls /usr/local/bin/brev

# Verify CLI is in PATH
which brev

# Verify CLI works
brev --help
```

The `brev --help` command should display the CLI help output.

## Rollback

To remove the installed CLI:

```bash
sudo rm -f /usr/local/bin/brev
```

## Why This Happens

The nested shell command `sudo bash -c "$(curl ...)"` can fail silently in certain shell configurations. Running the script directly provides better visibility into any errors that occur during installation.

## Alternative Installation Methods

If the script installation continues to fail, you can install using Homebrew (if available on your system):

```bash
brew install brevdev/homebrew-brev/brev
```

Or download the binary directly from the [Brev CLI releases page](https://github.com/brevdev/brev-cli/releases).

# CLI SSH Authentication (macOS)

> Resolve Brev CLI SSH authentication failures caused by invalid or corrupted SSH keys on macOS.

This guide helps you resolve Brev CLI authentication failures on macOS when SSH key issues prevent connection to your instances.

**Platform**: macOS

## Problem

On macOS systems, Brev CLI commands such as `brev ls`, `brev login`, or `brev ssh` fail with authentication or connection errors.

**Typical symptoms include:**

* `Permission denied (publickey)`
* `Could not establish SSH connection`
* `Error: connection closed unexpectedly`

This issue occurs when the local SSH key used by Brev (`~/.brev/brev.pem`) becomes invalid, corrupted, or has incorrect file permissions.

## Prerequisites

* macOS with Brev CLI installed (`brew install brevdev/homebrew-brev/brev`)
* Access to Brev dashboard or web app
* Terminal access with user home directory permissions

## Solution

Choose one of the following approaches to resolve the issue.

### Option 1: Re-authenticate Using Token (Recommended)

### Open account settings

Go to Brev Dashboard → Account Settings: [https://brev.nvidia.com/settings/account](https://brev.nvidia.com/settings/account)

### Navigate to CLI settings

Click on **CLI** in the settings menu.

### Copy the token

Copy the authentication token displayed on the page.

### Authenticate in terminal

Paste the token in your terminal when prompted by:

```bash
brev login --token
```

### Verify connection

```bash
brev ls
```

The command should list all available instances without error.

### Option 2: Regenerate SSH Key

### Check for existing Brev key

```bash
ls -l ~/.brev/brev.pem
```

If the file is missing or has incorrect permissions, proceed to the next step.

### Backup and remove old key

```bash
mv ~/.brev/brev.pem ~/.brev/brev.pem.bak
```

### Generate a new Brev key

1. Go to the [Brev Dashboard](https://brev.nvidia.com)
2. Navigate to **Profile → SSH Keys**
3. Re-download or generate a new `.brev.pem` file

### Set correct file permissions

```bash
chmod 600 ~/.brev/brev.pem
```

### Re-authenticate with Brev

```bash
brev login
brev ls
```

Verify the connection is successful.

## Verification

After completing either option:

* `brev ls` lists all available instances without error
* `brev ssh <instance-name>` connects successfully to the instance
* No permission or key errors appear in terminal output

## Workaround

If key regeneration fails:

* Temporarily use the [Brev Web Dashboard](https://brev.nvidia.com) for instance access
* Restore the previous key if needed:

```bash
mv ~/.brev/brev.pem.bak ~/.brev/brev.pem
chmod 600 ~/.brev/brev.pem
```

# Instance Stuck in Waiting State

> Diagnose and resolve NVIDIA Brev instances that remain indefinitely in "Waiting" state during provisioning.

This guide helps you resolve instances that fail to transition from "Waiting" to "Running" state during provisioning.

## Problem

Newly created instances remain indefinitely in a "Waiting" state on the Brev dashboard and CLI. Attempts to access the instance using `brev ssh` or `brev ls` show the instance as pending, and startup logs indicate incomplete provisioning.

**Common symptoms include:**

* Instance creation request succeeds but never transitions to "Running"
* `rpc error: code = Internal desc = context deadline exceeded`
* No `instance_id` or `public_ip` assigned in CLI output

## Prerequisites

* Access to Brev dashboard and CLI
* Valid Brev account with sufficient resource quota
* Organization owner or admin permissions (for quota-related issues)

## Solution

### Confirm instance state

```bash
brev ls
```

Verify that the affected instance shows "Waiting" status.

### Check recent activity

1. Open the instance details page in the Brev dashboard
2. Navigate to the **Activity Logs** tab
3. Look for recent provisioning or startup attempts
4. Note any error messages or failed operations

### Retry provisioning

1. Delete the stalled instance using the dashboard
2. Wait 30 seconds
3. Recreate the instance with the same configuration

### If the issue persists

Collect the following information for support:

* Logs from the instance details page
* Timestamps of creation attempts
* Your organization ID and instance configuration

## Verification

After recreating the instance:

* The newly created instance shows "Running" in both dashboard and CLI
* SSH access via `brev shell <instance-name>` is successful
* The instance has a valid `public_ip` assigned

## Workarounds

If repeated attempts fail:

* **Create with different name**: Create a fresh instance under a different name
* **Try alternative region**: Switch regions (for example, from `aws-us-east-1` to `aws-us-west-2`)
* **Use existing instances**: For critical workloads, use existing running instances until the backend issue is resolved

## Getting Help

If the issue persists after trying these solutions, contact support at [brev-support@nvidia.com](mailto:brev-support@nvidia.com) with:

* Your organization ID
* Instance name and configuration
* Timestamps of failed provisioning attempts
* Screenshots of activity logs showing errors

# GPU Detection and PyTorch Setup

> Resolve GPU detection issues with PyTorch, CUDA, and Unsloth on H100 instances.

This guide helps you resolve GPU detection issues when using PyTorch, CUDA, and machine learning frameworks like Unsloth on H100 instances.

**Platform**: AWS H100 instances, NGC containers

## Problem

Users running machine learning frameworks on H100 instances report errors when importing modules or when GPUs are not detected by PyTorch.

**Typical symptoms include:**

* `RuntimeError: CUDA error: no CUDA-capable device is detected`
* `torch.cuda.is_available() == False`
* Unsloth import fails or defaults to CPU

This occurs when the runtime environment lacks proper CUDA and PyTorch enablement for H100 GPUs.

## Prerequisites

* H100 or compatible NVIDIA GPU instance (for example, AWS H100)
* Docker and NVIDIA Container Toolkit installed
* Internet access to pull NGC containers or PyTorch wheels

## Solution

### Option 1: Use Official NGC PyTorch Container (Recommended)

The NGC PyTorch container includes verified CUDA and cuDNN versions for H100 GPUs.

### Launch the container

Replace `<PATH>` with your local project path:

```bash
sudo docker run --rm -it \
   --gpus all \
   -v <PATH>:/workspace \
   -w /workspace \
   nvcr.io/nvidia/pytorch:24.09-py3
```

### Install and test your framework

Inside the container, install and verify your ML framework:

```bash
pip install -U unsloth unsloth-zoo
python - <<'PY'
from unsloth import FastLanguageModel
print("Unsloth import OK")
PY
```

### Option 2: Manual Setup in Existing Environment

If you need to use your current Python environment:

### Check GPU visibility

```bash
nvidia-smi || echo "no NVIDIA detected"
echo $NVIDIA_VISIBLE_DEVICES
cat /proc/driver/nvidia/version 2>/dev/null | head -1
```

### Verify PyTorch sees the GPU

```python
import torch
print("cuda_available:", torch.cuda.is_available())
print("torch_cuda:", torch.version.cuda)
print("device_count:", torch.cuda.device_count())
print("name0:", torch.cuda.get_device_name(0) if torch.cuda.is_available() else None)
```

### Install CUDA-enabled PyTorch

If NVIDIA is visible but PyTorch shows CPU-only, install CUDA wheels:

```bash
pip uninstall -y torch torchvision torchaudio
pip install --index-url https://download.pytorch.org/whl/cu124 torch torchvision torchaudio
```

### Install your ML framework

```bash
pip install -U unsloth unsloth-zoo
```

### Test GPU detection

```bash
python -c "import unsloth; print('GPU available:', unsloth.torch.cuda.is_available())"
```

## Common Issues

### PyTorch installed without CUDA support

**Symptom**: `torch.cuda.is_available()` returns `False` or `ModuleNotFoundError: No module named 'torch'`

**Fix**: Reinstall PyTorch with CUDA support:

```bash
pip uninstall -y torch torchvision torchaudio
pip install --index-url https://download.pytorch.org/whl/cu124 \
    torch torchvision torchaudio
```

### Missing dependencies (xformers, torchao)

**Error examples**:

* `unsloth ... requires xformers>=0.0.27.post2`
* `unsloth-zoo ... requires torchao>=0.13.0`

**Fix**: Install required extras:

```bash
pip install xformers torchao
```

These dependencies are optional. Unsloth may work without them depending on your use case.

### GPU visible in nvidia-smi but Python cannot import torch

**Cause**: Torch installed in a different environment or missing from PATH.

**Fix**: Reinstall in the correct environment:

```bash
which python3
python3 -m pip install --force-reinstall torch
```

## Verification

After completing the setup:

* `nvidia-smi` lists the H100 GPU with no Xid or driver errors
* `torch.cuda.is_available()` returns `True`
* `from unsloth import FastLanguageModel` runs without error
* Model training or inference runs utilize the GPU (visible via `nvidia-smi` process list)

## Workaround

If the container or CUDA installation fails, revert to CPU-only mode temporarily:

```bash
pip uninstall unsloth unsloth-zoo
pip install unsloth-cpu
```

Alternatively, use an older NGC PyTorch container (for example, `23.10-py3`) for temporary compatibility.

## Additional Resources

* [NVIDIA NGC PyTorch Containers](https://catalog.ngc.nvidia.com/orgs/nvidia/containers/pytorch)
* [PyTorch CUDA Wheels](https://download.pytorch.org/whl/)

H100 GPUs typically require modern drivers (>= 550 recommended) and PyTorch cu124 wheels. Unsloth doesn't support AMD/CPU paths—it requires NVIDIA CUDA or Intel XPU.

# VS Code Connection (Windows/WSL)

> Configure VS Code Remote SSH to work with NVIDIA Brev Cloudflare Tunnel on Windows with WSL.

This guide helps you configure VS Code to connect to Brev instances when using Windows with WSL (Windows Subsystem for Linux).

**Platform**: Windows with WSL (Ubuntu or similar)

## Problem

When running the following command to open a Brev instance in VS Code:

```bash
brev open <instance_name> code
```

The connection fails with errors such as:

```
posix_spawnp: No such file or directory
WARN: $PLATFORM is undefined in installation script output
Failed to parse remote port from server output
Resolver error: Error
```

VS Code does not successfully establish an SSH session to the instance.

## Root Cause

When launching VS Code from WSL (for example, via `brev open <instance_name> code`), the editor runs as a Windows application and uses the Windows SSH client by default.

Although the `.brev` directory (SSH config and private key) is correctly synced from WSL to Windows, the `cloudflared` binary is not available to the Windows SSH client. Cloudflare Tunnel requires `cloudflared` to be executed as part of the SSH `ProxyCommand`, which Windows SSH cannot do when the binary exists only inside WSL.

As a result, VS Code fails to connect to Brev instances that depend on Cloudflare Tunnel-based SSH access.

## Prerequisites

* Windows host with VS Code installed
* WSL (for example, Ubuntu) configured and functional
* Brev CLI installed and authenticated in WSL

## Solution

Configure VS Code to use the WSL SSH client instead of the Windows SSH client.

### Create a wrapper BAT file

Create a file on Windows (for example, `C:\Users\<username>\wsl-ssh.bat`) with the following content:

```bat
C:\Windows\System32\wsl.exe ssh %*
```

This wrapper redirects SSH commands invoked by VS Code to the WSL SSH client.

### Open VS Code settings

1. Open VS Code
2. Press `Ctrl+,` to open Settings
3. Search for "remote.SSH.path"

### Configure the SSH path

Set the **Remote > SSH: Path** setting to the full Windows path of the `wsl-ssh.bat` file you created:

```
C:\Users\<username>\wsl-ssh.bat
```

Replace `<username>` with your Windows username.

### Save and restart

1. Save the settings
2. Restart VS Code

## Verification

After completing the configuration:

```bash
brev open <instance_name> code
```

* VS Code successfully connects to the instance over SSH
* Cloudflare Tunnel-based connections work without `posix_spawnp` or SSH binary errors
* You can browse files and use the integrated terminal on the remote instance

## Rollback

To revert to the default configuration:

1. Open VS Code Settings
2. Search for "remote.SSH.path"
3. Clear the value to restore the default
4. Restart VS Code

## Workaround

If you cannot configure VS Code, use a terminal-based SSH connection from WSL instead:

```bash
brev shell <instance_name>
```

This provides full terminal access to the instance without requiring VS Code Remote SSH integration.