# Tabby — User Guide

Tabby is a cross-platform terminal emulator built on Electron, designed to replace the default terminals on Windows, macOS, and Linux with a modern, extensible, feature-rich experience. It supports local shells, SSH, serial port, and telnet/socket connections through a unified tabbed interface with split panes, a plugin ecosystem, encrypted credential storage, and deep customization.

This guide covers everything you need to get productive with Tabby — from installation through advanced workflows. For architecture details, deployment internals, and plugin development, see the [Admin Guide](/guides/Eugeny/tabby/admin-guide/).

---

## 1. Quick Start

### 30-second setup

1. Download the installer for your platform from [GitHub Releases](https://github.com/Eugeny/tabby/releases/latest)
2. Run the installer (or extract the portable archive)
3. Launch Tabby — a local terminal tab opens automatically

That is it. Tabby ships with sensible defaults: your system's default shell, dark theme, WebGL-accelerated rendering, and 25,000 lines of scrollback.

### First things to try

| Action | How |
|--------|-----|
| Open a new tab | `Ctrl-Shift-T` (Win/Linux) or `Cmd-T` (macOS) |
| Split the terminal | `Ctrl-Shift-S` right / `Ctrl-Shift-D` bottom (Win/Linux) |
| Open the command palette | `Ctrl-Shift-P` (Win/Linux) or `Cmd-Shift-P` (macOS) |
| Quick-connect SSH | `Ctrl-Shift-E` profile selector, or `tabby quickConnect ssh user@host` |
| Search terminal output | `Ctrl-Shift-F` (Win/Linux) or `Cmd-F` (macOS) |
| Toggle window visibility | `Ctrl-Space` (all platforms — quake-style dropdown) |

> [!TIP]
> Press `Ctrl-Shift-P` (or `Cmd-Shift-P` on macOS) at any time to open the command palette. It is the fastest way to discover every action Tabby supports — type a few letters and the list narrows instantly.

### The Tabby CLI

Tabby registers a `tabby` command and the `tabby://` URL protocol. From any system terminal:

```bash
# Open Tabby in a specific directory
tabby open ~/projects/myapp

# Run a command in a new Tabby tab
tabby run htop

# Launch a saved SSH profile
tabby profile "Production Server"

# Start minimized (tray/dock only)
tabby --hidden
```

---

## 2. Installation

### Pre-built binaries (recommended)

Download the latest release from [github.com/Eugeny/tabby/releases](https://github.com/Eugeny/tabby/releases/latest). Choose the package that matches your OS and architecture:

#### Windows

| Package | Description |
|---------|-------------|
| `tabby-setup-x64.exe` | Standard installer (recommended) |
| `tabby-portable-x64.zip` | Portable — no install, runs from any folder |

Run the `.exe` installer and follow the prompts. For the portable version, extract the ZIP to any location and run `Tabby.exe` directly.

> [!IMPORTANT]
> On Windows, Tabby uses ConPTY by default (`terminal.useConPTY: true`). This requires Windows 10 version 1809 or later. If you experience rendering issues on older builds, set `terminal.useConPTY: false` in your config.

#### macOS

| Package | Description |
|---------|-------------|
| `tabby.dmg` | Standard disk image |

Open the `.dmg`, drag Tabby to Applications, and launch. macOS may prompt you to approve the app in System Preferences > Security & Privacy on first launch.

#### Linux

| Package | Description |
|---------|-------------|
| `tabby.deb` | Debian/Ubuntu (dpkg/apt) |
| `tabby.rpm` | Fedora/RHEL/openSUSE (rpm/dnf) |
| `tabby.AppImage` | Universal — runs on any distro |
| `tabby.snap` | Snap package (devmode confinement) |
| `tabby.pacman` | Arch Linux |

Install examples:

```bash
# Debian/Ubuntu
sudo dpkg -i tabby-*.deb
sudo apt-get install -f   # resolve dependencies if needed

# Fedora/RHEL
sudo rpm -i tabby-*.rpm

# Arch Linux
sudo pacman -U tabby-*.pacman

# Snap
sudo snap install tabby --devmode

# AppImage (no install needed)
chmod +x tabby-*.AppImage
./tabby-*.AppImage
```

> [!WARNING]
> The Snap package uses `devmode` confinement, which grants broader system access than strict Snap confinement. This is required because terminal emulators need unrestricted access to spawn processes, read filesystems, and manage PTYs.

### Package managers

Community-maintained packages are available through several package managers:

```bash
# macOS — Homebrew
brew install --cask tabby

# Windows — Chocolatey
choco install tabby

# Windows — Winget
winget install Eugeny.Tabby
```

> [!NOTE]
> Package manager versions are community-maintained and may lag behind the official GitHub releases by a few days.

### Building from source

Requirements: Node.js (LTS recommended), Yarn.

```bash
git clone https://github.com/Eugeny/tabby.git
cd tabby
yarn install
yarn build
yarn start
```

For a distributable package:

```bash
yarn build
yarn package        # creates platform-specific installer
```

### Portable mode

To run Tabby in portable mode (config and data stored next to the executable rather than in your user profile):

1. Place a `data/` folder next to the Tabby executable
2. Tabby detects the `PORTABLE_EXECUTABLE_FILE` environment and stores all configuration inside that `data/` directory

This is useful for USB drives, shared machines, or environments where you cannot write to the user profile.

### Migrating from Terminus

If you previously used Terminus (Tabby's former name), Tabby automatically migrates your configuration. On first launch, it checks for `../terminus/config.yaml` relative to its own config directory and imports settings transparently. No manual action required.

---

## 3. Configuration

Tabby stores its configuration in a single YAML file. The settings UI (accessed via the gear icon or `Ctrl-,` / `Cmd-,`) writes to this file, but you can also edit it directly for fine-grained control.

### Config file location

| Platform | Default path |
|----------|-------------|
| Windows | `%APPDATA%\tabby\config.yaml` |
| macOS | `~/Library/Application Support/tabby/config.yaml` |
| Linux | `~/.config/tabby/config.yaml` |

Override the location by setting the `TABBY_CONFIG_DIRECTORY` environment variable before launching Tabby:

```bash
# Linux/macOS
export TABBY_CONFIG_DIRECTORY=~/my-tabby-config
tabby

# Windows (PowerShell)
$env:TABBY_CONFIG_DIRECTORY = "D:\TabbyConfig"
tabby
```

Tabby creates a `config.yaml.backup` automatically each time it saves, so you always have a one-version rollback.

### Appearance

#### Window frame and transparency

```yaml
appearance:
  frame: thin            # thin | full | none
  opacity: 1.0           # 0.0 (fully transparent) to 1.0 (opaque)
  vibrancy: false        # macOS vibrancy / Windows acrylic (true/false)
  tabsLocation: top      # top | bottom | left | right
  theme: "Follow the color scheme"
```

The `thin` frame removes the native title bar and uses Tabby's own compact title bar. Set `frame: none` to remove the title bar entirely (window is still draggable from the tab bar).

#### Color schemes

Tabby ships with two built-in schemes:

- **Tabby Default** (dark)
- **Tabby Default Light**

Over 150 community color schemes are available through the settings UI, including popular options like Dracula, Nord, Solarized Dark/Light, Gruvbox, One Dark, Monokai, Tomorrow Night, and many more.

```yaml
appearance:
  colorSchemeMode: dark   # dark | light
```

To switch: Settings > Appearance > Color scheme, or search "color scheme" in the command palette.

You can also import Hyper color schemes — Tabby's linkifier module handles the translation automatically.

#### Quake-style dropdown mode

Tabby can function as a dropdown terminal (like Guake or Yakuake) that slides in from a screen edge when you press a hotkey:

```yaml
appearance:
  dock: off              # off | top | bottom | left | right
  dockFill: 0.5          # fraction of screen to fill (0.0-1.0)
  dockSpace: 1           # space between screen edge and window
  dockAlwaysOnTop: true  # keep above other windows
  dockHideOnBlur: false  # hide when focus leaves Tabby
```

Set `dock` to any edge and configure a global hotkey (Settings > Hotkeys > "Toggle terminal window", default `Ctrl-Space`) to toggle visibility. Combined with `--hidden` on the CLI, Tabby starts invisible and only appears when summoned.

### Terminal settings

```yaml
terminal:
  autoOpen: true         # open a tab automatically on launch
  useConPTY: true        # Windows: use ConPTY (disable for legacy apps)
  font: Consolas         # Windows default; Menlo on macOS, Liberation Mono on Linux
  fontSize: 14
  fontLigatures: true    # render programming ligatures (Fira Code, JetBrains Mono, etc.)
  cursor: block          # block | beam | underline
  cursorBlink: true
  scrollbackLines: 25000
  colorScheme:
    name: "Tabby Default"
  copyOnSelect: true     # Windows default; false on macOS/Linux
  pasteOnMiddleClick: true  # macOS/Linux; false on Windows
  sixel: true            # inline image rendering (Sixel protocol)
  bell: "off"            # off | notification | sound
  bracketedPaste: true   # protect against paste injection
  warnOnMultiLinePaste: true
  trimWhitespaceOnPaste: true
  rightClick: menu       # menu | paste | off
  searchRegex: false
  wordSeparator: ' ()[]{}\'"'
```

> [!TIP]
> For the best visual experience with font ligatures, install a ligature-capable font like [Fira Code](https://github.com/tonsky/FiraCode), [JetBrains Mono](https://www.jetbrains.com/lp/mono/), or [Cascadia Code](https://github.com/microsoft/cascadia-code), then set `terminal.font` to its name and ensure `terminal.fontLigatures: true`.

### Window behavior

```yaml
recoverTabs: true              # restore tabs on restart
enableAutomaticUpdates: true   # check for updates on launch
hideTray: false                # show tray icon (Windows/Linux)
```

### Hacks and experimental

```yaml
hacks:
  disableGPU: false                    # force software rendering
  disableVibrancyWhileDragging: false  # workaround for vibrancy drag artifacts
  enableFluentBackground: false        # Windows Fluent Design background
  globalHotkey: null                   # raw hotkey accelerator string
enableExperimentalFeatures: false      # unlock experimental plugin features
```

Set `hacks.disableGPU: true` if you experience graphical glitches, especially in VMs or with older GPU drivers. This forces CPU-based rendering at the cost of some performance.

### Plugin management

```yaml
pluginBlacklist: []      # list of plugin package names to disable
commandBlacklist: []     # list of command IDs to hide from the palette
```

User-installed plugins live in `{userData}/plugins/`. The settings UI provides a plugin manager that handles install, update, and removal. Plugins are npm packages under the hood — Tabby runs `npm install` in the plugins directory.

### Profiles

Profiles are saved connection configurations — local shells, SSH hosts, serial ports, or telnet endpoints. Create them in Settings > Profiles & Connections, or they are generated automatically when you connect.

Profiles can specify:

- Shell or connection type
- Working directory
- Environment variables
- Color scheme override
- Font override
- Custom title
- Icon and color label
- Command to run on connect

For the full configuration reference and all available YAML keys, see the [Admin Guide](/guides/Eugeny/tabby/admin-guide/).

---

## 4. Core Usage

### Managing tabs

Tabby's tabbed interface is the primary way to organize multiple sessions.

| Action | Windows/Linux | macOS |
|--------|--------------|-------|
| New tab | `Ctrl-Shift-T` | `Cmd-T` |
| Close tab | `Ctrl-Shift-W` | `Cmd-W` |
| Next tab | `Ctrl-Tab` | `Ctrl-Tab` |
| Previous tab | `Ctrl-Shift-Tab` | `Ctrl-Shift-Tab` |
| Go to tab N | `Alt-1` through `Alt-0` | `Cmd-1` through `Cmd-9` |
| Cycle tabs | `Ctrl-Tab` (cycles in order) | `Ctrl-Tab` |
| Move tab | Drag the tab header | Drag the tab header |
| Duplicate tab | Right-click tab > Duplicate | Right-click tab > Duplicate |
| Rename tab | Double-click the tab title | Double-click the tab title |
| Pin tab | Right-click tab > Pin | Right-click tab > Pin |

> [!TIP]
> Enable `appearance.cycleTabs: true` (the default) to wrap around when pressing Next/Previous tab at the end/beginning of the tab bar.

Tab cycling is enabled by default. When you close Tabby and reopen it, all tabs are restored to their previous state (controlled by `recoverTabs: true`).

### Split panes

Split any tab into multiple panes to view terminals side-by-side:

| Action | Windows/Linux | macOS |
|--------|--------------|-------|
| Split right | `Ctrl-Shift-S` | `Cmd-Shift-D` |
| Split bottom | `Ctrl-Shift-D` | `Cmd-D` |
| Navigate between panes | `Ctrl-Shift-Arrow` | `Cmd-Shift-Arrow` |
| Close pane | Close the shell (type `exit`) or `Ctrl-Shift-W` |

Drag the divider between panes to resize. Each pane is an independent terminal session — it can run a different shell, SSH connection, or serial port.

> [!TIP]
> Combine splits with profiles: right-click a pane divider area and select "Split right with profile..." to open a specific SSH connection alongside your local terminal.

### The command palette

Press `Ctrl-Shift-P` (Win/Linux) or `Cmd-Shift-P` (macOS) to open the command palette. Every action in Tabby is registered as a command, and the palette provides fuzzy search across all of them.

Common palette commands:

- `New Tab` — open a new local terminal
- `Profile: [name]` — open a saved profile
- `Toggle Fullscreen` — enter/exit fullscreen (`F11`)
- `Copy` / `Paste` — clipboard operations
- `Search` — open the in-terminal search bar
- `Settings` — open the settings UI
- `Reload Config` — re-read `config.yaml` without restarting
- `Plugin Manager` — manage installed plugins
- `Restart SSH Session` — reconnect an SSH tab
- `Toggle SFTP Panel` — open/close the SFTP file browser

### Profile selector

Press `Ctrl-Shift-E` (Win/Linux) or `Cmd-E` (macOS) to open the profile selector. This shows all your saved profiles grouped by type (Local, SSH, Serial, Telnet) for quick launching.

### Copy and paste

| Action | Windows/Linux | macOS |
|--------|--------------|-------|
| Copy | `Ctrl-Shift-C` | `Cmd-C` |
| Paste | `Ctrl-Shift-V` | `Cmd-V` |
| Copy on select | Enabled by default (Windows) | Disabled by default |
| Paste on middle click | Disabled by default (Windows) | Enabled by default |

> [!WARNING]
> **Multiline paste warning:** When you paste text containing newlines, Tabby shows a confirmation dialog by default. This protects against accidentally pasting commands that execute immediately in a shell. Disable with `terminal.warnOnMultiLinePaste: false` — but understand the risk.

Additional clipboard behaviors:

- **Trim whitespace on paste** (`terminal.trimWhitespaceOnPaste: true`): strips leading/trailing whitespace from pasted text
- **Bracketed paste** (`terminal.bracketedPaste: true`): wraps pasted text in escape sequences so the shell knows it was pasted, not typed — prevents accidental command injection in shells that support it (bash, zsh, fish)

### Searching terminal output

Press `Ctrl-Shift-F` (Win/Linux) or `Cmd-F` (macOS) to open the search bar. It searches through the terminal's scrollback buffer (up to 25,000 lines by default).

Search options (toggle via icons in the search bar):

| Option | Description |
|--------|-------------|
| Case sensitive | Match exact case |
| Whole word | Match complete words only |
| Regex | Use regular expressions |

Navigate matches with Enter (next) and Shift-Enter (previous), or use the arrow buttons.

### Fullscreen mode

Press `F11` (Win/Linux) or use the command palette on macOS to toggle fullscreen. In fullscreen, the tab bar remains visible unless you have only one tab open and have configured `appearance.frame: none`.

### Using the CLI

The `tabby` command-line interface lets you control Tabby from any external terminal or script:

```bash
tabby [command] [arguments]
```

#### Commands

**`open [directory]`** — Open a new tab in the specified directory:

```bash
tabby open /var/log
tabby open .                  # current directory
tabby open ~/projects/myapp
```

**`run [command...]`** (alias: `/k`) — Run a command in a new Tabby tab:

```bash
tabby run htop
tabby run tail -f /var/log/syslog
tabby /k npm start            # /k alias works the same way
```

**`profile [profileName]`** — Launch a saved profile by name:

```bash
tabby profile "Production DB"
tabby profile "Dev Server SSH"
```

**`paste [text]`** — Paste text into the active terminal:

```bash
tabby paste "ls -la"
tabby paste -e "path with spaces"   # -e enables shell escaping
```

**`recent [index]`** — Reopen a recently closed tab:

```bash
tabby recent         # most recent
tabby recent 0       # most recent (explicit)
tabby recent 2       # third most recent
```

**`quickConnect <providerId> <query>`** — Quick-connect to a host:

```bash
tabby quickConnect ssh user@hostname
tabby quickConnect ssh root@192.168.1.100
```

#### Global options

| Option | Description |
|--------|-------------|
| `--debug` / `-d` | Launch with DevTools open (useful for troubleshooting plugins) |
| `--hidden` | Start minimized to tray/dock — useful for quake-mode setups |

#### URL protocol

Tabby registers the `tabby://` protocol handler. Click or open `tabby://` URLs from browsers, scripts, or other applications to trigger Tabby actions:

```
tabby://open?path=/home/user/projects
tabby://profile?name=My+SSH+Server
```

### Tray icon

On Windows and Linux, Tabby shows a system tray icon by default. Right-click it to:

- Show/hide the window
- Open a new tab
- Launch a profile
- Quit Tabby

Set `hideTray: true` to remove the tray icon.

---

## 5. Common Tasks

### Local terminal workflows

#### Opening your preferred shell on Windows

Tabby auto-detects available shells on Windows. Out of the box, it finds:

| Shell | Notes |
|-------|-------|
| Command Prompt (cmd.exe) | Always available |
| PowerShell (Windows) | Built-in `powershell.exe` |
| PowerShell Core | If `pwsh.exe` is installed |
| Git Bash | If Git for Windows is installed |
| Cygwin | If Cygwin is installed |
| MSYS2 | If MSYS2 is installed |
| WSL | Each installed distribution appears separately |
| Cmder | If Cmder is installed and on PATH |
| VS Developer Tools | Visual Studio developer command prompts |

Create a profile for your preferred shell: Settings > Profiles & Connections > New Profile > Local Terminal, then select the shell from the dropdown.

#### Setting a default shell

1. Open Settings > Profiles & Connections
2. Find or create the profile for your preferred shell
3. Click the star icon to set it as default
4. New tabs (`Ctrl-Shift-T`) will now use that shell

#### Setting a working directory

Per-profile working directories:

1. Edit the profile in Settings > Profiles & Connections
2. Set the "Working directory" field to your preferred path
3. Every new tab using that profile starts in that directory

Or use the CLI: `tabby open /path/to/directory`

#### Environment variables

Set per-profile environment variables in the profile editor. These are merged with the system environment when the shell launches.

#### Running a command on tab open

In the profile editor, set the "Command" field. The command runs inside the shell after it starts. Useful for auto-SSH, auto-tmux, or launching tools.

### SSH connections

#### Creating an SSH profile

1. Settings > Profiles & Connections > New Profile > SSH
2. Fill in host, port (default 22), username
3. Choose authentication method:
   - Password (stored in the Vault if configured)
   - Private key file
   - SSH agent (pageant, ssh-agent, etc.)
4. Save the profile

Or quick-connect from the command palette: type `ssh user@host` in the profile selector.

#### Authentication methods

Tabby's SSH implementation (built on the `russh` native library) supports:

| Method | Configuration |
|--------|--------------|
| Password | Enter in profile or store in Vault |
| Private key file | Browse to `.pem`, `.ppk`, or OpenSSH key |
| SSH agent | Auto-detected (ssh-agent, Pageant, macOS Keychain) |
| Agent forwarding | Enable per-profile |
| Keyboard-interactive | Prompted at connect time |

Supported key algorithms include `ssh-ed25519`, `rsa-sha2-256`, `rsa-sha2-512`, `ecdsa-sha2-nistp256/384/521`, and legacy `ssh-rsa`.

Default key exchange algorithms include post-quantum `mlkem768x25519-sha256` and modern `curve25519-sha256`. Default ciphers include `chacha20-poly1305@openssh.com` and `aes256-gcm`.

#### Importing OpenSSH config

Tabby can import hosts from your `~/.ssh/config` file. In Settings > Profiles & Connections, click "Import from OpenSSH config" to create profiles for each host entry. This imports hostname, user, port, identity file, proxy jump, and other directives.

#### Jump hosts (proxy jump)

Configure multi-hop SSH through bastion/jump hosts:

1. Edit an SSH profile
2. In the "Jump host" section, select another SSH profile to use as the jump host
3. Tabby establishes the connection through the intermediary

You can chain multiple jump hosts for complex network topologies.

#### Port forwarding

Tabby supports three types of SSH port forwarding, all configurable per-profile:

**Local forwarding** — Access a remote service through a local port:

```
Local port 3306 → remote-db:3306
```

This makes `localhost:3306` on your machine connect to `remote-db:3306` through the SSH tunnel.

**Remote forwarding** — Expose a local service to the remote network:

```
Remote port 8080 → localhost:3000
```

This makes port 8080 on the remote server connect back to your local port 3000.

**Dynamic forwarding (SOCKS proxy)** — Create a SOCKS5 proxy through the SSH tunnel:

```
Dynamic port 1080
```

Configure your browser or application to use `localhost:1080` as a SOCKS5 proxy to route traffic through the remote server.

Configure port forwarding in the SSH profile under "Port forwarding", or add them on-the-fly from a connected SSH tab via the command palette.

#### SFTP file browser

Every SSH connection includes an integrated SFTP panel. Toggle it with the command palette ("Toggle SFTP Panel") or the SFTP icon in the tab toolbar.

The SFTP panel provides:

- Directory browsing with breadcrumb navigation
- File upload (drag and drop or browse)
- File download
- File/directory rename and delete
- Permission viewing

#### X11 forwarding

Enable X11 forwarding in the SSH profile to run graphical applications on the remote host and display them locally. Requires an X server on your local machine (Xming or VcXsrv on Windows, XQuartz on macOS, native X11 on Linux).

#### Proxy support

Tabby SSH connections can route through HTTP or SOCKS proxies:

1. Edit the SSH profile
2. Under "Proxy", select the proxy type (HTTP or SOCKS5)
3. Enter the proxy host and port
4. Optionally provide proxy authentication credentials

#### Session multiplexing

When connecting to the same SSH host multiple times, Tabby can multiplex connections over a single TCP session (similar to OpenSSH's `ControlMaster`). This speeds up subsequent connections and reduces authentication prompts.

#### Keepalive

SSH profiles include a keepalive setting that sends periodic packets to prevent idle disconnections. Configure the interval in seconds in the profile editor.

#### Host key verification

On first connection, Tabby prompts you to verify the remote host's key fingerprint. Accepted keys are stored and verified on subsequent connections. If a key changes (possible man-in-the-middle), Tabby warns before connecting.

#### Auto-sudo password

For SSH sessions where you frequently need sudo, Tabby can detect sudo password prompts and automatically paste your saved password. Enable this per-profile and store the password in the Vault.

> [!CAUTION]
> Auto-sudo sends your password automatically whenever a sudo-like prompt is detected. Use this only on trusted hosts where you control the shell environment, as a malicious process could mimic a sudo prompt to capture credentials.

### Serial port connections

Tabby includes a full-featured serial terminal for hardware debugging, embedded development, and console access.

#### Creating a serial profile

1. Settings > Profiles & Connections > New Profile > Serial
2. Select the serial port (auto-detected from the system)
3. Configure communication parameters:

| Parameter | Options | Default |
|-----------|---------|---------|
| Baud rate | 110 to 1,500,000 | 9600 |
| Data bits | 5, 6, 7, 8 | 8 |
| Stop bits | 1, 1.5, 2 | 1 |
| Parity | None, Even, Odd, Mark, Space | None |
| Flow control | None, RTS/CTS, XON/XOFF | None |

#### Common baud rates

| Rate | Typical use |
|------|------------|
| 9600 | Default for most devices, Cisco IOS console |
| 19200 | Some industrial equipment |
| 38400 | GPS modules, some modems |
| 57600 | Faster serial devices |
| 115200 | Most modern devices, Raspberry Pi, Arduino |
| 230400+ | High-speed embedded, FTDI at max |

#### Slow-send mode

For devices with limited input buffers (older PLCs, microcontrollers with no flow control), enable slow-send mode. This inserts a brief delay between each character transmitted, preventing buffer overruns.

### Telnet and raw socket connections

#### Telnet

1. Settings > Profiles & Connections > New Profile > Telnet
2. Enter host and port (default: 23)
3. Connect

Telnet connections support local echo mode (for half-duplex devices) and readline mode.

#### Raw socket

For protocols that do not use Telnet negotiation:

1. Create a new Telnet profile
2. Set the connection type to "Raw socket"
3. Enter host and port (default: 1234)

Raw socket mode sends data byte-for-byte without Telnet escape handling — useful for custom TCP protocols, MUD clients, or testing servers.

### The Vault (encrypted credential storage)

The Vault stores sensitive data — SSH passwords, private key passphrases, and sudo passwords — encrypted with a master passphrase.

#### Setting up the Vault

1. Settings > Vault
2. Set a master passphrase
3. The Vault is now active

When you save an SSH profile with a password, Tabby offers to store it in the Vault instead of in plaintext in `config.yaml`.

#### Using the Vault

- Credentials stored in the Vault are decrypted only when needed (at connection time)
- You enter the Vault passphrase once per session (or each time, depending on your lock settings)
- The Vault uses a versioned encryption format (currently version 1)

> [!WARNING]
> If you forget your Vault passphrase, stored credentials cannot be recovered. Keep a backup of your SSH keys and passwords separately. The Vault is a convenience layer, not a backup mechanism.

### File transfers with ZMODEM

Tabby supports ZMODEM file transfer protocol. When a ZMODEM transfer is initiated from the remote side (via `sz` or `rz` commands), Tabby automatically detects it and handles the transfer:

**Download (remote to local):**

```bash
# On the remote host
sz filename.tar.gz
```

Tabby prompts for a local save location.

**Upload (local to remote):**

```bash
# On the remote host
rz
```

Tabby opens a file picker to select the file to upload.

### Sixel image rendering

Tabby renders inline images using the Sixel protocol (enabled by default with `terminal.sixel: true`). Applications that output Sixel graphics (like `img2sixel`, `lsix`, or `matplotlib` with Sixel backend) display images directly in the terminal.

```bash
# Install img2sixel (Debian/Ubuntu)
sudo apt install libsixel-bin

# Display an image inline
img2sixel photo.png
```

### Color scheme management

#### Switching color schemes

1. Settings > Appearance > Color scheme
2. Browse the 150+ available schemes
3. Click to preview, click again to apply

Or use the command palette: "Color scheme" and select from the list.

#### Dark and light modes

```yaml
appearance:
  colorSchemeMode: dark    # dark | light
  theme: "Follow the color scheme"
```

When `theme` is set to "Follow the color scheme", the entire UI (not just the terminal) adapts to the color scheme's dark/light orientation.

### Keyboard shortcut customization

All hotkeys are customizable in Settings > Hotkeys. The full default mapping:

#### Windows and Linux defaults

| Action | Shortcut |
|--------|----------|
| New tab | `Ctrl-Shift-T` |
| Close tab | `Ctrl-Shift-W` |
| Next tab | `Ctrl-Tab` |
| Previous tab | `Ctrl-Shift-Tab` |
| Tab 1-10 | `Alt-1` through `Alt-0` |
| Command palette | `Ctrl-Shift-P` |
| Profile selector | `Ctrl-Shift-E` |
| Toggle window | `Ctrl-Space` |
| Fullscreen | `F11` |
| Split right | `Ctrl-Shift-S` |
| Split bottom | `Ctrl-Shift-D` |
| Search | `Ctrl-Shift-F` |
| Copy | `Ctrl-Shift-C` |
| Paste | `Ctrl-Shift-V` |

#### macOS defaults

| Action | Shortcut |
|--------|----------|
| New tab | `Cmd-T` |
| Close tab | `Cmd-W` |
| Profile selector | `Cmd-E` |
| Command palette | `Cmd-Shift-P` |
| Toggle window | `Ctrl-Space` |
| Split bottom | `Cmd-D` |
| Split right | `Cmd-Shift-D` |
| Search | `Cmd-F` |
| Copy | `Cmd-C` |
| Paste | `Cmd-V` |
| Tab 1-9 | `Cmd-1` through `Cmd-9` |

To change a shortcut: Settings > Hotkeys, click the shortcut next to the action, press your desired key combination.

### Setting a global hotkey

A global hotkey works even when Tabby is not focused — ideal for quake-mode dropdown usage:

1. Settings > Hotkeys > find "Toggle terminal window"
2. The default is `Ctrl-Space`
3. Change it to any combination that does not conflict with other applications

Or set it directly in config:

```yaml
hacks:
  globalHotkey: "Ctrl+`"    # raw Electron accelerator string
```

### Window management recipes

#### Recipe: Quake-style dropdown from top of screen

```yaml
appearance:
  dock: top
  dockFill: 0.4          # 40% of screen height
  dockAlwaysOnTop: true
  dockHideOnBlur: true   # hide when you click away
```

Launch with `tabby --hidden` and press `Ctrl-Space` to summon.

#### Recipe: Sidebar terminal on the right

```yaml
appearance:
  dock: right
  dockFill: 0.3          # 30% of screen width
  dockAlwaysOnTop: true
  dockHideOnBlur: false
```

#### Recipe: Fullscreen terminal workspace

```yaml
appearance:
  frame: none
  dock: off
terminal:
  autoOpen: true
recoverTabs: true
```

Launch, press `F11` for fullscreen, then use splits to create a tiled workspace.

#### Recipe: Transparent terminal over code editor

```yaml
appearance:
  opacity: 0.85
  dock: off
  dockAlwaysOnTop: true
  frame: thin
```

### Multi-shell development layout

Set up a project workspace with multiple shells:

1. Open Tabby and navigate to your project: `tabby open ~/projects/myapp`
2. Split right (`Ctrl-Shift-S`): run your dev server in the right pane
3. Split the right pane bottom (`Ctrl-Shift-D`): run tests or logs
4. You now have three panes: editor terminal, server, and logs

With `recoverTabs: true`, this layout persists across restarts.

### SSH tunnel recipes

#### Recipe: Access a remote database through SSH

```
Profile: "Staging DB Tunnel"
Host: bastion.example.com
Port forwarding:
  Local: 5432 → staging-db.internal:5432
```

Connect the profile, then use `psql -h localhost -p 5432` on your local machine.

#### Recipe: Browse remote web app through SOCKS proxy

```
Profile: "Dev SOCKS"
Host: dev-server.example.com
Port forwarding:
  Dynamic: 1080
```

Connect, then configure your browser to use `localhost:1080` as a SOCKS5 proxy.

#### Recipe: Expose local dev server to remote colleagues

```
Profile: "Reverse Tunnel"
Host: shared-server.example.com
Port forwarding:
  Remote: 8080 → localhost:3000
```

Connect, and colleagues can access your local app at `shared-server:8080`.

#### Recipe: Multi-hop SSH to production

```
Profile: "Jump Host" → bastion.example.com
Profile: "Production" → 10.0.1.50
  Jump host: "Jump Host"
```

Tabby connects to the bastion first, then tunnels through to the internal host.

#### Recipe: SSH with HTTP proxy in corporate environment

```
Profile: "External Server"
Host: server.example.com
Proxy:
  Type: HTTP
  Host: corporate-proxy.internal
  Port: 3128
  Username: employee123
```

### Serial port recipes

#### Recipe: Cisco switch console

```
Profile: "Cisco Console"
Port: COM3 (or /dev/ttyUSB0)
Baud: 9600
Data bits: 8
Stop bits: 1
Parity: None
Flow control: None
```

#### Recipe: Arduino serial monitor

```
Profile: "Arduino"
Port: COM4 (or /dev/ttyACM0)
Baud: 115200
Data bits: 8
Stop bits: 1
Parity: None
```

#### Recipe: Raspberry Pi UART

```
Profile: "RPi UART"
Port: /dev/ttyAMA0
Baud: 115200
Data bits: 8
Stop bits: 1
Parity: None
```

#### Recipe: Slow device with buffer issues

```
Profile: "Legacy PLC"
Port: COM1
Baud: 9600
Slow-send mode: enabled
```

### Plugin management

#### Installing plugins

1. Settings > Plugins
2. Browse the available plugin list
3. Click "Install" next to the desired plugin
4. Restart Tabby (some plugins require restart)

Or install via command line:

```bash
cd ~/.config/tabby/plugins     # Linux
cd ~/Library/Application\ Support/tabby/plugins   # macOS
cd %APPDATA%\tabby\plugins     # Windows

npm install tabby-plugin-name
```

#### Disabling plugins without uninstalling

Add the plugin's package name to the blacklist:

```yaml
pluginBlacklist:
  - tabby-telnet          # disables the telnet/socket plugin
  - tabby-community-color-schemes
```

#### Hiding commands from the palette

If a plugin adds commands you never use:

```yaml
commandBlacklist:
  - "telnet:new-tab"
  - "serial:new-tab"
```

### Localization

Tabby supports 24+ languages. Change the language in Settings > Application > Language, or via `config.yaml`. The UI, menus, and settings labels update without restart.

### Automatic updates

By default, Tabby checks for updates on launch (`enableAutomaticUpdates: true`). When an update is available, a notification appears with options to download and install.

Disable with:

```yaml
enableAutomaticUpdates: false
```

### Working with WSL (Windows Subsystem for Linux)

Tabby auto-detects all installed WSL distributions. Each appears as a separate profile option in the local terminal list. You can:

- Open any WSL distro in a new tab
- Set a WSL distro as your default shell
- Use WSL shells in split panes alongside Windows shells
- Access Windows files from WSL via `/mnt/c/`

### Clickable links in terminal output

Tabby's linkifier automatically detects and makes clickable:

- URLs (`https://...`, `http://...`)
- IP addresses
- File paths (platform-aware)

Click a link to open it in your default browser, or Cmd/Ctrl-click to force-open. Right-click a link for options including copy.

> [!NOTE]
> If links open in the wrong browser, this is controlled by your operating system's default browser setting, not Tabby. Check your OS default applications settings.

### Quick Connect

The default quick connect provider is SSH. From anywhere in Tabby:

1. Press `Ctrl-Shift-E` to open the profile selector
2. Type `user@hostname` directly into the search field
3. Tabby creates an ad-hoc SSH connection

Or from the command line:

```bash
tabby quickConnect ssh root@192.168.1.1
```

Change the default provider in config:

```yaml
defaultQuickConnectProvider: ssh    # ssh | telnet | serial
```

---

## 6. Troubleshooting

> [!IMPORTANT]
> Before troubleshooting, check which version you are running: Settings > About, or `tabby --version`. Many issues are fixed in newer releases. Tabby is currently at version `1.0.231-nightly.0`.

> [!TIP]
> Launch Tabby with `tabby --debug` (or `-d`) to open DevTools. The console output often reveals the exact error, especially for plugin and rendering issues.

### Startup issues

---

#### Tabby will not start / crashes on launch

**Error:** Application window never appears, or appears briefly and closes.

**Cause:** GPU driver incompatibility, corrupted config file, or missing system library.

**Solution:**

1. Try disabling GPU acceleration:
   - Find your `config.yaml` and add:
     ```yaml
     hacks:
       disableGPU: true
     ```
   - Or set the environment variable: `DISABLE_GPU=1 tabby`

2. If that does not help, rename your config file to start fresh:
   ```bash
   # Linux
   mv ~/.config/tabby/config.yaml ~/.config/tabby/config.yaml.bak
   
   # macOS
   mv ~/Library/Application\ Support/tabby/config.yaml ~/Library/Application\ Support/tabby/config.yaml.bak
   
   # Windows (PowerShell)
   Rename-Item "$env:APPDATA\tabby\config.yaml" "config.yaml.bak"
   ```

3. Launch Tabby — it creates a fresh default config

**Prevention:** Keep `config.yaml.backup` (Tabby creates this automatically). If you edit config manually, validate YAML syntax before saving.

---

#### "Cannot create process, error 267" on Windows

**Error:** `Cannot create process error 267` when opening a new tab.

**Cause:** The working directory configured in the profile does not exist or has been deleted. Error 267 is Windows for "directory name is invalid."

**Solution:**

1. Open Settings > Profiles & Connections
2. Edit the affected profile
3. Clear the "Working directory" field or set it to a valid path (e.g., `C:\Users\YourName`)
4. Save and try again

**Prevention:** Avoid hardcoding paths to removable drives or temporary directories in profiles.

---

#### Stuck on shell name (e.g., "CMD (clink)") — tab opens but no prompt appears

**Error:** Tab opens with the shell title but the terminal shows no prompt and does not accept input.

**Cause:** A shell integration or extension (like Clink for CMD) is interfering with the terminal initialization. This can also happen if the shell binary is not found at the expected path.

**Solution:**

1. Create a new profile with the plain shell (e.g., `cmd.exe` directly, not through Clink)
2. If using Clink, ensure Clink is properly installed and on your PATH
3. Check if the shell binary exists at the configured path
4. Try with ConPTY disabled: `terminal.useConPTY: false` in config

**Prevention:** Test shell integrations by launching the shell manually from cmd first.

---

#### Crash on Ubuntu 24.04

**Error:** Tabby crashes immediately or shortly after launch on Ubuntu 24.04.

**Cause:** Ubuntu 24.04 ships with newer system libraries that may conflict with the Electron version Tabby uses. Commonly a glibc or libGL issue.

**Solution:**

1. Try the AppImage version instead of the .deb package
2. If using the .deb, install missing dependencies:
   ```bash
   sudo apt-get install -f
   ```
3. Try with GPU disabled:
   ```bash
   tabby --disable-gpu
   ```
4. Check for Wayland issues — try forcing X11:
   ```bash
   GDK_BACKEND=x11 tabby
   ```

**Prevention:** Prefer the AppImage on newer distro releases until the .deb package is updated.

---

### SSH issues

---

#### SSH key authentication fails

**Error:** Connection fails with "Authentication failed" despite having the correct key configured.

**Cause:** Multiple possible causes — key format incompatibility, wrong permissions, agent not running, or a regression in key handling.

**Solution:**

1. Verify the key works with the OpenSSH command-line client:
   ```bash
   ssh -i ~/.ssh/mykey user@host -v
   ```

2. Check key format — Tabby supports OpenSSH and PEM formats. Convert if needed:
   ```bash
   ssh-keygen -p -m PEM -f ~/.ssh/mykey    # convert to PEM
   ```

3. Ensure the SSH agent is running if using agent auth:
   ```bash
   eval $(ssh-agent)
   ssh-add ~/.ssh/mykey
   ```

4. Try password auth as a workaround while debugging key issues

5. On macOS, if the key path contains a `~`, try using the absolute path instead (e.g., `/Users/yourname/.ssh/id_ed25519`)

**Prevention:** Prefer `ed25519` keys (shorter, faster, universally supported in modern SSH). Test keys with the command-line `ssh` client before adding to Tabby.

---

#### SSH login fails with CA-signed keys

**Error:** Authentication rejected when using SSH certificates (CA-signed keys).

**Cause:** Tabby's SSH library may not fully support certain CA certificate formats or options.

**Solution:**

1. Verify the certificate is valid:
   ```bash
   ssh-keygen -L -f ~/.ssh/id_ed25519-cert.pub
   ```

2. Ensure both the private key AND the certificate are accessible to Tabby

3. As a workaround, try adding the key to your SSH agent and using agent-based auth in Tabby instead of direct key file reference

**Prevention:** Test CA-signed key authentication with command-line `ssh -v` first to confirm it works at the SSH protocol level.

---

#### Auto-disconnect after connecting through jump server

**Error:** SSH connection through a jump host establishes successfully but disconnects after a short period.

**Cause:** Keepalive packets not reaching the final host through the jump chain, or the jump host timing out idle forwarded connections.

**Solution:**

1. Enable keepalive on both the jump host profile and the final host profile
2. Set keepalive interval to 15-30 seconds
3. On the jump host, ensure `AllowTcpForwarding yes` is set in `sshd_config`
4. Increase `ClientAliveInterval` on the final host's sshd_config

**Prevention:** Always configure keepalive for jump host connections. Set it on every profile in the chain.

---

#### SSH connection hangs on disconnect

**Error:** When an SSH session disconnects (network issue, server reboot), the tab hangs instead of showing a "disconnected" state.

**Cause:** The TCP connection is in a half-open state — the local side does not know the remote is gone.

**Solution:**

1. Close the tab manually (`Ctrl-Shift-W`)
2. Enable keepalive with a short interval (15-30 seconds) to detect dead connections faster
3. If the tab is completely unresponsive, use the command palette to force-close it

**Prevention:** Enable keepalive on all SSH profiles. This is the single most effective setting for reliable SSH connections.

---

### Terminal rendering issues

---

#### Graphical glitches or corruption

**Error:** Terminal output shows garbled text, missing characters, or visual artifacts.

**Cause:** GPU driver issues with WebGL rendering (`xterm-webgl`).

**Solution:**

1. Disable GPU acceleration:
   ```yaml
   hacks:
     disableGPU: true
   ```

2. If the issue is specific to certain characters or emoji, check your font supports them. Try a Nerd Font or a font with broad Unicode coverage.

3. Update your GPU drivers

4. On VMs, GPU passthrough may not support WebGL — disable GPU acceleration

**Prevention:** Keep GPU drivers current. If running in a VM, disable GPU acceleration proactively.

---

#### Font rendering looks wrong

**Error:** Fonts appear blurry, too thin, too bold, or have wrong spacing.

**Cause:** Font name mismatch, missing font, or subpixel rendering differences.

**Solution:**

1. Verify the font name matches exactly:
   ```yaml
   terminal:
     font: "JetBrains Mono"   # exact name as installed
     fontSize: 14
   ```

2. Check the font is installed system-wide (not just for the current user on some OSes)

3. Try disabling ligatures if spacing looks wrong:
   ```yaml
   terminal:
     fontLigatures: false
   ```

4. Adjust font size — some fonts render poorly at certain sizes

**Prevention:** Stick to well-tested terminal fonts: JetBrains Mono, Fira Code, Cascadia Code, or the platform defaults.

---

#### High memory usage

**Error:** Tabby consumes several GB of RAM.

**Cause:** Large scrollback buffers across many tabs, memory leaks in long-running sessions, or plugins leaking memory.

**Solution:**

1. Reduce scrollback:
   ```yaml
   terminal:
     scrollbackLines: 5000     # down from 25000 default
   ```

2. Close tabs you are not using — each tab holds its full scrollback in memory

3. Restart Tabby periodically for long-running sessions

4. Check installed plugins — disable them one at a time to identify memory-hungry plugins:
   ```yaml
   pluginBlacklist:
     - "suspect-plugin-name"
   ```

5. Check DevTools (Memory tab) with `tabby --debug` to profile

**Prevention:** Use conservative scrollback for sessions that produce heavy output (logs, builds). Consider piping verbose output to files instead.

---

#### Scrolling issues with certain applications

**Error:** Scrolling behaves unexpectedly inside terminal applications (e.g., less, vim, Claude Code).

**Cause:** Interaction between the terminal's scrollback, the application's alternate screen buffer, and mouse reporting.

**Solution:**

1. Some applications use the alternate screen buffer (which disables scrollback) — this is normal behavior
2. If scrolling is completely broken, check if mouse reporting is enabled and try toggling it
3. For specific applications, check if they have their own scroll settings

**Prevention:** Understand that terminal applications that use alternate screen buffer (vim, less, htop) intentionally disable terminal scrollback while running.

---

### Connection issues

---

#### Serial port not detected

**Error:** The serial port dropdown is empty or missing your device.

**Cause:** Missing USB-to-serial driver, device permissions, or device not connected.

**Solution:**

1. Verify the device is visible to the OS:
   ```bash
   # Linux
   ls /dev/ttyUSB* /dev/ttyACM*
   
   # macOS
   ls /dev/tty.usbserial* /dev/tty.usbmodem*
   
   # Windows — check Device Manager > Ports (COM & LPT)
   ```

2. Install the USB-to-serial driver (FTDI, CH340, CP210x) for your adapter

3. On Linux, add yourself to the `dialout` group:
   ```bash
   sudo usermod -a -G dialout $USER
   # Log out and back in for the group change to take effect
   ```

4. Refresh the port list in Tabby (close and reopen the profile editor)

**Prevention:** Install USB-serial drivers before connecting the device.

---

#### Telnet connection refused

**Error:** "Connection refused" when connecting via Telnet.

**Cause:** The telnet service is not running on the target, firewall blocking port 23, or wrong port.

**Solution:**

1. Verify the service is running on the target:
   ```bash
   nc -zv target-host 23      # test port connectivity
   ```

2. Try the correct port — many devices use non-standard telnet ports

3. Check firewalls between your machine and the target

4. For network equipment, try the console port (serial) if telnet is disabled

**Prevention:** Verify port connectivity with `nc` or `telnet` from the command line before creating a profile.

---

### Clipboard issues

---

#### Copy/paste not working

**Error:** `Ctrl-Shift-C` / `Ctrl-Shift-V` does not copy or paste.

**Cause:** Hotkey conflict with another application, or clipboard permissions issue on Wayland.

**Solution:**

1. Verify the hotkeys in Settings > Hotkeys — they may have been changed
2. On Wayland (Linux), clipboard access requires specific permissions. Try running under X11:
   ```bash
   GDK_BACKEND=x11 tabby
   ```
3. Check if "Copy on select" is more reliable for your setup:
   ```yaml
   terminal:
     copyOnSelect: true
   ```

**Prevention:** Use copy-on-select as an alternative to keyboard shortcuts.

---

#### Pasted text appears garbled

**Error:** Pasted text has extra characters, formatting, or line endings.

**Cause:** Rich text on the clipboard (from web pages, Word docs) or bracketed paste mode interacting unexpectedly with the shell.

**Solution:**

1. Enable whitespace trimming:
   ```yaml
   terminal:
     trimWhitespaceOnPaste: true
   ```

2. If brackets appear around pasted text, the shell does not support bracketed paste. Disable it:
   ```yaml
   terminal:
     bracketedPaste: false
   ```

3. Copy from a plain text editor instead of rich-text sources

**Prevention:** Use `Ctrl-Shift-V` in the source application to "paste as plain text" before copying to Tabby.

---

### Plugin issues

---

#### Plugin fails to install

**Error:** Plugin installation fails with npm errors.

**Cause:** Network issues, npm registry unavailable, or Node.js version mismatch.

**Solution:**

1. Check your internet connection
2. Try installing from the command line to see detailed errors:
   ```bash
   cd ~/.config/tabby/plugins   # or your platform's plugin path
   npm install tabby-plugin-name --verbose
   ```
3. Clear the npm cache:
   ```bash
   npm cache clean --force
   ```
4. Check if a proxy is required in your network

**Prevention:** Keep Node.js updated. If behind a corporate proxy, configure npm to use it.

---

#### Plugin causes Tabby to crash

**Error:** Tabby crashes or becomes unresponsive after installing a plugin.

**Cause:** Plugin incompatibility with the current Tabby version or a bug in the plugin.

**Solution:**

1. Start Tabby with the plugin disabled. Edit `config.yaml`:
   ```yaml
   pluginBlacklist:
     - "problematic-plugin-name"
   ```

2. If you cannot start Tabby at all, delete the plugin directory:
   ```bash
   # Linux
   rm -rf ~/.config/tabby/plugins/node_modules/tabby-problem-plugin
   
   # macOS
   rm -rf ~/Library/Application\ Support/tabby/plugins/node_modules/tabby-problem-plugin
   ```

3. Report the issue on the plugin's GitHub repository

**Prevention:** Install plugins one at a time and verify stability before installing the next.

---

### Environment and shell issues

---

#### Environment variables not available in terminal

**Error:** Environment variables set in `.bashrc` / `.zshrc` are not available in Tabby's terminal.

**Cause:** Tabby launches shells as login or non-login shells depending on the platform, which affects which startup files are sourced.

**Solution:**

1. Check which startup files your shell reads. For bash:
   - Login shell: `~/.bash_profile` or `~/.profile`
   - Non-login shell: `~/.bashrc`

2. Ensure your environment setup is in the file that gets sourced. The most portable approach:
   ```bash
   # In ~/.bash_profile, source .bashrc
   if [ -f ~/.bashrc ]; then
       source ~/.bashrc
   fi
   ```

3. Set environment variables in the Tabby profile editor for guaranteed availability

4. On macOS, GUI applications do not inherit terminal environment variables. Use `launchctl setenv` or set variables in the profile.

**Prevention:** Always put environment configuration in `~/.bashrc` and source it from `~/.bash_profile`.

---

#### `setlocale` warning on launch

**Error:** Warning message about `setlocale` when opening a terminal tab.

**Cause:** The locale configured in your environment is not installed on the system.

**Solution:**

```bash
# Check current locale
locale

# Generate the missing locale (Debian/Ubuntu)
sudo locale-gen en_US.UTF-8
sudo dpkg-reconfigure locales

# Verify
locale
```

**Prevention:** Ensure `LANG`, `LC_ALL`, and related variables point to installed locales.

---

#### Links open in wrong browser

**Error:** Clicking URLs in the terminal opens a browser other than your default.

**Cause:** The default browser is set at the OS level, not in Tabby. On Linux, `xdg-settings` controls this.

**Solution:**

```bash
# Linux — check default browser
xdg-settings get default-web-browser

# Linux — set default browser
xdg-settings set default-web-browser firefox.desktop

# macOS — set in System Preferences > General > Default web browser

# Windows — Settings > Apps > Default apps > Web browser
```

**Prevention:** This is an OS-level setting, not a Tabby setting.

---

### Performance issues

---

#### Slow rendering with many tabs

**Error:** UI becomes sluggish with 10+ tabs open.

**Cause:** Each tab maintains its own terminal instance and scrollback buffer, consuming memory and GPU resources.

**Solution:**

1. Close unused tabs
2. Reduce scrollback:
   ```yaml
   terminal:
     scrollbackLines: 5000
   ```
3. Ensure GPU acceleration is working (do not disable it unless you have to)
4. Check if vibrancy/transparency is enabled — it increases GPU load:
   ```yaml
   appearance:
     vibrancy: false
     opacity: 1.0
   ```

**Prevention:** Keep tab count reasonable. Use splits within a single tab instead of many tabs when working on the same project.

---

#### Input lag / delayed keystroke display

**Error:** Typed characters appear with a noticeable delay.

**Cause:** GPU driver issues, high CPU usage, or network latency (for SSH sessions).

**Solution:**

1. For local terminals:
   - Disable vibrancy and transparency
   - Disable font ligatures (they add rendering overhead)
   - Update GPU drivers

2. For SSH sessions:
   - Check network latency: `ping target-host`
   - Enable compression in the SSH profile
   - Consider if the remote host is overloaded

**Prevention:** Disable visual effects you do not need. For SSH, use the closest geographic server or enable compression.

---

### Vault issues

---

#### Forgot Vault passphrase

**Error:** Cannot access stored credentials because the Vault passphrase is forgotten.

**Cause:** The Vault encryption is one-way — no recovery without the passphrase.

**Solution:**

1. Delete the Vault data to reset:
   - Settings > Vault > Reset Vault
   - Or delete the encrypted vault data from `config.yaml`

2. Re-enter all stored passwords and keys

3. The Vault is reset — set a new passphrase

**Prevention:** Use a password manager to store your Vault passphrase. Keep independent backups of SSH keys and critical passwords.

---

#### Vault prompts for passphrase repeatedly

**Error:** Tabby asks for the Vault passphrase multiple times per session.

**Cause:** The Vault lock timeout is set too short, or a plugin is triggering repeated decryption requests.

**Solution:**

1. Check Vault lock settings in Settings > Vault
2. Extend the lock timeout
3. If a specific connection triggers it, check if multiple credentials in that profile each require decryption

**Prevention:** Use SSH agent-based auth instead of stored passwords for frequently-accessed hosts — it avoids the Vault entirely.

---

### Update issues

---

#### Automatic update fails

**Error:** Update notification appears but the update fails to download or install.

**Cause:** Network issues, insufficient permissions (on some Linux installations), or antivirus blocking the download.

**Solution:**

1. Download the update manually from [GitHub Releases](https://github.com/Eugeny/tabby/releases)
2. Close Tabby completely
3. Install the new version over the existing installation
4. On Linux, if using .deb:
   ```bash
   sudo dpkg -i tabby-latest.deb
   ```

**Prevention:** If auto-update consistently fails, disable it and update manually:
```yaml
enableAutomaticUpdates: false
```

---

## 7. FAQ

**Q: What platforms does Tabby support?**
Tabby runs on Windows 10/11 (x64), macOS (Intel and Apple Silicon via universal binary), and Linux (x64). Installers are available as .exe, .dmg, .deb, .rpm, .AppImage, .snap, and .pacman packages.

**Q: Is Tabby free?**
Yes. Tabby is open source under the MIT license. Free to use for personal and commercial purposes.

**Q: How is Tabby different from Windows Terminal, iTerm2, or Alacritty?**
Tabby is cross-platform (the same app on all three OSes), has built-in SSH with connection management, includes a serial terminal, supports plugins for extensibility, and provides an encrypted credential vault. Windows Terminal is Windows-only; iTerm2 is macOS-only; Alacritty focuses on performance and minimal features.

**Q: Does Tabby support tabs and split panes?**
Yes. Unlimited tabs, and each tab can be split horizontally and vertically into as many panes as you need. Each pane can run a different shell or connection.

**Q: Can I use Tabby as a drop-down (quake-style) terminal?**
Yes. Set `appearance.dock` to `top`, `bottom`, `left`, or `right`, configure a global hotkey (default `Ctrl-Space`), and start Tabby with `--hidden`. It slides in when you press the hotkey and hides when you press it again or click away (if `dockHideOnBlur: true`).

**Q: How do I make the window transparent?**
Set `appearance.opacity` to a value less than 1.0 (e.g., 0.85 for 85% opacity). On macOS and Windows, you can also enable `appearance.vibrancy: true` for a native blur effect behind the window.

**Q: Where does Tabby store its configuration?**
In a `config.yaml` file inside the user data directory: `%APPDATA%\tabby` (Windows), `~/Library/Application Support/tabby` (macOS), or `~/.config/tabby` (Linux). Override with the `TABBY_CONFIG_DIRECTORY` environment variable. Tabby also creates a `.backup` copy automatically.

**Q: Can I use Tabby in portable mode?**
Yes. Place a `data/` folder next to the Tabby executable. All configuration and plugin data will be stored there instead of in your user profile.

**Q: How do I import my SSH config?**
Settings > Profiles & Connections > Import from OpenSSH config. Tabby reads `~/.ssh/config` and creates a profile for each host entry, preserving hostname, user, port, identity file, and proxy jump settings.

**Q: Does Tabby support SSH key authentication?**
Yes. Tabby supports OpenSSH keys, PEM keys, and SSH agent forwarding. Key types include ed25519, RSA (sha2-256/512), ECDSA, and legacy RSA. Keys can be stored in the encrypted Vault.

**Q: What SSH algorithms does Tabby support?**
Modern defaults: `mlkem768x25519-sha256` (post-quantum key exchange), `chacha20-poly1305@openssh.com`, `aes256-gcm`, `ssh-ed25519`, `rsa-sha2-256/512`. Legacy algorithms are available but not enabled by default.

**Q: Can I connect through a jump/bastion host?**
Yes. In an SSH profile, set the "Jump host" to another SSH profile. Tabby connects through the intermediary. You can chain multiple jump hosts.

**Q: Does Tabby have an SFTP client?**
Yes. Every SSH connection includes an SFTP panel. Toggle it from the command palette or the tab toolbar. It supports browsing, upload, download, rename, and delete.

**Q: How do I set up port forwarding?**
In the SSH profile editor, under "Port forwarding". Tabby supports local, remote, and dynamic (SOCKS) forwarding. You can add forwards before connecting or on-the-fly from a live session.

**Q: Can I use Tabby with WSL?**
Yes. Tabby auto-detects all installed WSL distributions. Each appears as a separate local terminal option.

**Q: Does Tabby support serial connections?**
Yes. Tabby includes a serial terminal supporting baud rates from 110 to 1,500,000, configurable data bits (5-8), stop bits (1/1.5/2), parity, and flow control (RTS/CTS, XON/XOFF). Slow-send mode is available for devices with limited input buffers.

**Q: Can I display images in the terminal?**
Yes. Tabby supports the Sixel protocol for inline image rendering (enabled by default). Use tools like `img2sixel` or `lsix` on the remote or local host.

**Q: How do I change the color scheme?**
Settings > Appearance > Color scheme. Over 150 community color schemes are available in addition to the two built-in schemes (Tabby Default dark and Tabby Default Light).

**Q: Can I customize keyboard shortcuts?**
Yes. Settings > Hotkeys shows all actions with their current bindings. Click any shortcut to change it. All default hotkeys are remappable.

**Q: What is the Vault?**
An encrypted credential store protected by a master passphrase. It securely holds SSH passwords, key passphrases, and sudo passwords so they do not appear in plaintext in your config file.

**Q: Does Tabby support font ligatures?**
Yes. Set `terminal.fontLigatures: true` (the default) and use a ligature-capable font like Fira Code, JetBrains Mono, or Cascadia Code.

**Q: Can I transfer files in the terminal?**
Yes, via ZMODEM. Use `sz` (send) and `rz` (receive) on the remote host. Tabby detects ZMODEM transfers automatically and handles the file dialogs. SFTP is also available for SSH connections.

**Q: How do I install plugins?**
Settings > Plugins. Browse, install, and manage plugins from the built-in plugin manager. Plugins are npm packages and can also be installed manually.

**Q: What if a plugin crashes Tabby?**
Add the plugin to `pluginBlacklist` in your `config.yaml` to disable it without uninstalling. If you cannot start Tabby, delete the plugin from the plugins directory manually.

**Q: Does Tabby support multiple languages?**
Yes. 24+ languages are supported. Change the language in Settings > Application > Language.

**Q: How does auto-update work?**
Tabby checks for updates on launch (controlled by `enableAutomaticUpdates: true`). When an update is found, a notification prompts you to download and install. You can also download updates manually from GitHub.

**Q: Can I use Tabby with Cmder?**
Yes, on Windows. If Cmder is installed and on your PATH, Tabby auto-detects it and offers it as a shell option.

**Q: How do I use the CLI to open a directory?**
Run `tabby open /path/to/directory` from any terminal. This opens a new Tabby tab in that directory.

**Q: What is the `tabby://` protocol?**
Tabby registers itself as a handler for `tabby://` URLs. You can open these from browsers, scripts, or other applications to trigger Tabby actions like opening directories or launching profiles.

**Q: How many lines of scrollback does Tabby keep?**
25,000 lines by default. Change with `terminal.scrollbackLines` in config. Higher values use more memory per tab.

**Q: Does Tabby support Telnet?**
Yes. Tabby includes a telnet client (default port 23) and raw socket connections (default port 1234). Both support local echo and readline modes.

**Q: Can I use Tabby for Cisco/network equipment console access?**
Yes. Use serial profiles for console cables (typically 9600/8/N/1) or telnet/SSH profiles for network connections. Tabby handles ANSI escape sequences used by Cisco IOS, JunOS, and other network operating systems.

---

_Generated May 2026 from Eugeny/tabby at d8fdecd. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._