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

# wezterm ssh

> Establish an SSH session with WezTerm

The `ssh` command establishes an SSH connection to a remote system using WezTerm's built-in SSH client.

## Synopsis

```bash theme={null}
wezterm ssh [OPTIONS] <USER_AT_HOST_AND_PORT> [PROG]...
```

## Description

Establishes an SSH session to a remote system. WezTerm includes a built-in SSH client that can parse SSH configuration files and provides a native terminal experience with full feature support.

## Arguments

<ParamField path="USER_AT_HOST_AND_PORT" type="string" required>
  Specifies the remote system using the form: `[username@]host[:port]`

  * If `username@` is omitted, your local `$USER` is used
  * If `:port` is omitted, the standard SSH port (22) is used

  **Examples:**

  ```bash theme={null}
  wezterm ssh user@example.com
  wezterm ssh example.com:2222
  wezterm ssh user@example.com:2222
  wezterm ssh example.com
  ```
</ParamField>

<ParamField path="PROG" type="string[]">
  Instead of executing your shell, run PROG on the remote system.

  **Example:**

  ```bash theme={null}
  wezterm ssh user@host -- bash -l
  ```

  This will spawn bash as if it were a login shell on the remote system.
</ParamField>

## Options

<ParamField path="-o, --ssh-option" type="name=value">
  Override specific SSH configuration options. Can be specified multiple times.

  WezTerm's SSH client can parse some (but not all!) options from your `~/.ssh/config` and `/etc/ssh/ssh_config` files. This command line switch allows you to override or otherwise specify ssh\_config style options.

  **Example:**

  ```bash theme={null}
  wezterm ssh -oIdentityFile=/secret/id_ed25519 some-host
  wezterm ssh -oPort=2222 -oUser=admin example.com
  ```
</ParamField>

<ParamField path="-v" type="flag">
  Enable verbose SSH protocol tracing.

  The trace information is printed to the stderr stream of the process. Useful for debugging connection issues.
</ParamField>

<ParamField path="--class" type="string">
  Override the default windowing system class. The default is `org.wezfurlong.wezterm`.

  * Under X11 and Windows: changes the window class
  * Under Wayland: changes the app\_id

  This changes the class for all windows spawned by this instance of wezterm, including error, update and ssh authentication dialogs.
</ParamField>

<ParamField path="--position" type="string">
  Override the position for the initial window launched by this process.

  **Format options:**

  * `--position 10,20` - set x=10, y=20 in screen coordinates
  * `--position screen:10,20` - set x=10, y=20 in screen coordinates
  * `--position main:10,20` - set x=10, y=20 relative to the main monitor
  * `--position active:10,20` - set x=10, y=20 relative to the active monitor
  * `--position HDMI-1:10,20` - set x=10, y=20 relative to the monitor named HDMI-1
</ParamField>

## Examples

### Basic SSH connection

```bash theme={null}
wezterm ssh user@example.com
```

### Connect to non-standard port

```bash theme={null}
wezterm ssh user@example.com:2222
```

### Use specific identity file

```bash theme={null}
wezterm ssh -oIdentityFile=~/.ssh/id_custom user@example.com
```

### Multiple SSH options

```bash theme={null}
wezterm ssh -oPort=2222 -oUser=admin -oIdentityFile=/path/to/key example.com
```

### Enable verbose debugging

```bash theme={null}
wezterm ssh -v user@example.com
```

### Run a specific command

```bash theme={null}
wezterm ssh user@example.com -- htop
```

### Open at specific window position

```bash theme={null}
wezterm ssh --position main:0,0 user@example.com
```

## SSH Configuration

WezTerm respects your SSH configuration files:

* `~/.ssh/config`
* `/etc/ssh/ssh_config`

You can define host aliases and settings in these files, and WezTerm will use them:

```ssh-config theme={null}
Host myserver
    HostName example.com
    User myuser
    Port 2222
    IdentityFile ~/.ssh/id_ed25519
```

Then simply:

```bash theme={null}
wezterm ssh myserver
```

## Features

* Built-in SSH client (no external SSH binary required)
* Supports SSH agent forwarding
* Respects SSH config files
* Full terminal feature support (colors, mouse, clipboard, etc.)
* Integrated with WezTerm's multiplexer capabilities

## Related

* [wezterm connect](/cli/connect) - Connect to pre-configured multiplexer domains
* [wezterm start](/cli/start) - Start a local terminal session