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.

1. Quick Start

30-second setup

1. Download the installer for your platform from GitHub Releases
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

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:

# 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. Choose the package that matches your OS and architecture:

Windows

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

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

Install examples:

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

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

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

For a distributable package:

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

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

# 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

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.

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:

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

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, JetBrains Mono, or Cascadia Code, then set terminal.font to its name and ensure terminal.fontLigatures: true.

Window behavior

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

Hacks and experimental

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

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.

4. Core Usage

Managing tabs

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

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:

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

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

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:

tabby [command] [arguments]

Commands

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

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

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

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:

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

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

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

recent [index] — Reopen a recently closed tab:

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

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

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

Global options

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:

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:

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:

Common baud rates

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

# On the remote host
sz filename.tar.gz

Tabby prompts for a local save location.

Upload (local to remote):

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

# 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

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

macOS defaults

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:

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

Window management recipes

Recipe: Quake-style dropdown from top of screen

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

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

Recipe: Fullscreen terminal workspace

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

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:

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:

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:

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:

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:

tabby quickConnect ssh root@192.168.1.1

Change the default provider in config:

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:

     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:

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

   sudo apt-get install -f
   

3. Try with GPU disabled:

   tabby --disable-gpu
   

4. Check for Wayland issues — try forcing X11:

   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:

   ssh -i ~/.ssh/mykey user@host -v
   

2. Check key format — Tabby supports OpenSSH and PEM formats. Convert if needed:

   ssh-keygen -p -m PEM -f ~/.ssh/mykey    # convert to PEM
   

3. Ensure the SSH agent is running if using agent auth:

   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:

   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:

   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:

   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:

   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:

   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:

   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:

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

   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:

   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:

   GDK_BACKEND=x11 tabby
   

3. Check if "Copy on select" is more reliable for your setup:

   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:

   terminal:
     trimWhitespaceOnPaste: true
   

2. If brackets appear around pasted text, the shell does not support bracketed paste. Disable it:

   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:

   cd ~/.config/tabby/plugins   # or your platform's plugin path
   npm install tabby-plugin-name --verbose
   

3. Clear the npm cache:

   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:

   pluginBlacklist:
     - "problematic-plugin-name"
   

2. If you cannot start Tabby at all, delete the plugin directory:

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

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

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

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

   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:

   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
2. Close Tabby completely
3. Install the new version over the existing installation
4. On Linux, if using .deb:

   sudo dpkg -i tabby-latest.deb
   

Prevention: If auto-update consistently fails, disable it and update manually:

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.