[Question]: Can you make keybinds fully passthrough?

[thatonelinuxguy]

Prerequisites

• I have searched existing issues and discussions
• I have reviewed the documentation (README, DOCS/, configuration files)
• This is not a bug report or feature request (use the appropriate template for those)

Question Category

Installation/Setup

WebSSH2 Version (if applicable)

latest

Question

How can you make the key binds EX: CTRL + Q passthrough the browser and go to the Webssh window. I am aware the CTRL works but only if the key bind dosen't exist in the browser.

Context

No response

Environment Details (if relevant)

No response

What Have You Tried?

-Development method: npm

• OS: Arch Linux
• SSH server type: OpenSSH

Additional Information

No response

[billchurch]

Thanks for the great question! This is something that comes up frequently with web-based terminal emulators, so I want to give a thorough answer.

The Browser Limitation

Unfortunately, most browser-reserved shortcuts like Ctrl+W, Ctrl+T, and Ctrl+N cannot be intercepted by any web application -- this includes webssh2, and every other web-based terminal out there. This is a deliberate security decision made by all major browsers:

• Chrome removed web page access to Ctrl+N/T/W starting with Chrome 4
• Firefox followed suit in version 48, marking it WONTFIX -- stating it prevents "malicious websites" from trapping users

The browser consumes these keystrokes before JavaScript ever sees them, so there's nothing a web page can do. The xterm.js maintainer has confirmed this as a fundamental browser limitation.

Other projects like VS Code for the Web, Apache Guacamole, noVNC, and ttyd all face the same limitation and document it accordingly.

What CAN Be Intercepted

Many shortcuts can be captured and passed through to the terminal session. webssh2 already captures some of these (Escape, Ctrl+B, and configurable custom keys via the settings modal). Shortcuts like Ctrl+S, Ctrl+F, Ctrl+P, Ctrl+D, and Ctrl+R can all be intercepted and forwarded.

Workarounds

Here are some options depending on your needs:

1. Keyboard Lock API (Chromium, Fullscreen Only)

The Keyboard Lock API (navigator.keyboard.lock()) can capture all keyboard shortcuts including Ctrl+W, Ctrl+T, and Ctrl+N. The catch is it requires:

• JavaScript-initiated fullscreen mode
• Chromium-based browser (Chrome, Edge, Opera) -- not supported on Firefox or Safari
• HTTPS
• User can always exit by holding Escape for 2 seconds

This is the most promising enhancement we could add to webssh2 -- an optional "fullscreen terminal" mode that activates keyboard lock on supported browsers. I'll look into adding this.

2. Run as a PWA / Chrome --app Mode

Running Chrome with --app=<your-webssh2-url> or installing webssh2 as a PWA removes the browser chrome (tabs, address bar) and can make some additional shortcuts available. Note that Ctrl+W may still close the app window in some cases.

3. Alternative Key Combinations

Some terminal-friendly alternatives that don't conflict with browser shortcuts:

• Ctrl+Shift+ variants (e.g., Ctrl+Shift+W) are often available since the browser only reserves the non-shift version

4. Electron / Desktop Wrapper

Using an Electron or Tauri wrapper gives full keyboard control -- this is how VS Code's desktop terminal achieves it. This is outside the scope of webssh2 itself, but if you need complete keyboard passthrough, a thin Electron wrapper around your webssh2 instance would work.

5. Browser Extensions

Extensions like "Disable Keyboard Shortcuts" for Chrome can remap or disable browser-reserved shortcuts, freeing them up for web applications. This requires per-user installation though.

What We Can Improve

Based on this, here are some things I'm considering for webssh2:

• Keyboard Lock API integration -- An optional fullscreen mode that captures all keys on supported browsers
• beforeunload protection -- A confirmation dialog to prevent accidental tab closure during active SSH sessions
• Special key sender panel -- A slide-out "visor" style panel along the edge of the terminal that lets you send browser-reserved key combinations (Ctrl+W, Ctrl+N, Ctrl+Q, etc.) with a click. Think of it like a compact toolbar that stays tucked away until you need it -- hover or tap to reveal it, click the key combo you need, and it gets sent straight to the SSH session. Apache Guacamole does something similar with an on-screen keyboard, but a focused panel of just the "unreachable" shortcuts would be lighter weight and more practical for everyday use.
• Better documentation -- Making the keyboard capture settings and their limitations more discoverable

Hope this helps clarify things! It's a frustrating limitation of the web platform, but there are paths forward depending on your use case.