CLI Reference

Connectivity

View as Markdown

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

$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

FlagDescription
--hostSSH into the host machine instead of the container.
--dir / -dOverride directory to launch shell.

brev open

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

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

EditorCommandRequirement
VS Codebrev open my-instance or brev open my-instance codeVS Code with Remote SSH extension.
Cursorbrev open my-instance cursorCursor installed in PATH.
Windsurfbrev open my-instance windsurfWindsurf installed in PATH.
tmuxbrev open my-instance tmuxInstalled automatically on instance.

Flags

FlagDescription
--hostSSH into the host machine instead of the container.
--wait / -wWait for setup to finish before opening.
--dir / -dSpecify directory to open.
--set-defaultSet 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.

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

FlagShortDescription
--port-pPort mapping in format local:remote
--hostUse the host version of the instance.

Common Port Forwards

ServicePortCommand
Jupyter8888--port 8888:8888
TensorBoard6006--port 6006:6006
Streamlit8501--port 8501:8501
Gradio7860--port 7860:7860

Direct SSH

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

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

2

Find Using Tunnels

Scroll to the Access section and locate Using Tunnels.

3

Add a Port

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

4

Copy the URL

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 CaseRecommended Method
Sharing with teammatesTunnels
Web UIs (Jupyter, Gradio)Tunnels
Direct API calls from scriptsPort forwarding
CI/CD integrationsPort forwarding
Testing locallyPort 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.

$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:

$curl ifconfig.me

What’s Next

VS Code Setup

Configure VS Code Remote SSH for full IDE features.

Jupyter Notebooks

Run JupyterLab with GPU acceleration.