Skip to navigation
CLI Reference

Connectivity

View as Markdown

Connect to your instances through shell, VS Code, or port forwarding. brev shell and brev port-forward also support Brev Connect machines after SSH is enabled and your Brev user has been granted access. Run connection commands on your local computer, use brev login with your user account, and select the machine’s organization with brev org set <organization-name>.

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. Managed instances use the workspace directory; Brev Connect machines use the Linux account associated with your SSH access grant.

Flags

FlagDescription
--hostSSH into the host machine instead of the container.

brev exec

Run a command on one or more instances without opening an interactive shell.

# brev exec [instance...] "<command>"
# brev exec [instance...] @<script-file-present-on-local>
# Run a command on an instance
brev exec my-instance "nvidia-smi"
# Run on multiple instances
brev exec instance1 instance2 instance3 "nvidia-smi"
# Run a script file on the instance (@ prefix reads local file)
brev exec my-instance @setup.sh
brev exec my-instance @scripts/deploy.sh
# Run a background job
brev exec my-instance "nohup python train.py > /dev/null 2>&1 &"

Quote the whole command. Everything before the final argument is treated as an instance name, so brev exec my-instance python train.py looks for an instance named python. Write brev exec my-instance "python train.py" instead.

Flags

FlagDescription
--hostRun the command on the host machine instead of the container.

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 a TCP port from your instance or Brev Connect machine to localhost over SSH. Start Jupyter, your web server, or another service on the remote port first.

# Forward specific port (local:remote)
brev port-forward my-instance --port 8888:8888
# Forward another port with a separate command
brev port-forward my-instance --port 6006:6006
# Interactive mode (prompts for ports)
brev port-forward my-instance

Use one command per port mapping. Repeating --port in the same command only uses the last value; UDP forwarding is not supported by this SSH command.

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.

For Brev Connect machines, the command also creates a remote TCP port binding that persists after local forwarding exits. Remove an unneeded binding with the beta command brev ports close <machine-name>, selecting its destination port.

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 configuration generated by Brev. This preserves the correct username, endpoint, port, and authentication settings, including certificates for Brev Connect machines.

# Update the configuration, then connect by instance or Brev Connect machine name
brev refresh
ssh my-instance
# Manual port forward with SSH
ssh -N -L LOCAL_PORT:localhost:REMOTE_PORT my-instance

Where:

  • LOCAL_PORT is the port on your local machine
  • REMOTE_PORT is the port on your Brev instance
  • my-instance is the SSH alias generated for your instance or Brev Connect machine

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.