From c9be4f9fa1781f0a69116a7efca6746c54e60d11 Mon Sep 17 00:00:00 2001 From: Steven Miller Date: Mon, 2 Feb 2026 14:21:45 -0500 Subject: [PATCH 1/4] Add SSH doc --- browsers/ssh.mdx | 84 ++++++++++++++++++++++++++++++++++++++ docs.json | 1 + reference/cli/browsers.mdx | 10 +++++ 3 files changed, 95 insertions(+) create mode 100644 browsers/ssh.mdx diff --git a/browsers/ssh.mdx b/browsers/ssh.mdx new file mode 100644 index 0000000..08914a0 --- /dev/null +++ b/browsers/ssh.mdx @@ -0,0 +1,84 @@ +--- +title: "SSH Access" +description: "Open an interactive SSH session to a browser VM" +--- + +SSH into a running Kernel browser VM for debugging, running commands, or setting up port forwarding. + +## Prerequisites + +The `kernel browsers ssh` command requires [websocat](https://github.com/vi/websocat) to be installed locally: + +```bash +# macOS +brew install websocat + +# Linux +curl -fsSL https://github.com/vi/websocat/releases/download/v1.13.0/websocat.x86_64-unknown-linux-musl \ + -o /usr/local/bin/websocat && chmod +x /usr/local/bin/websocat +``` + +## Basic usage + +Open an interactive SSH shell to a browser VM: + +```bash +kernel browsers ssh +``` + +By default, this generates an ephemeral ed25519 SSH keypair for the session. The keypair is automatically cleaned up when the session ends. + +## Using an existing SSH key + +Specify an existing SSH private key instead of generating an ephemeral one: + +```bash +kernel browsers ssh -i ~/.ssh/id_ed25519 +``` + + +The corresponding `.pub` file must exist alongside the private key (e.g., `~/.ssh/id_ed25519.pub`). + + +## Port forwarding + +Port forwarding uses standard SSH syntax. + +### Local forwarding (`-L`) + +Forward a local port to a port on the VM. Useful for accessing services running inside the VM from your local machine: + +```bash +# Access VM's port 5432 (e.g., a database) on local port 5432 +kernel browsers ssh -L 5432:localhost:5432 +``` + +### Remote forwarding (`-R`) + +Forward a VM port to a port on your local machine. Useful for exposing a local development server to the browser: + +```bash +# Expose local dev server (port 3000) on VM port 8080 +kernel browsers ssh -R 8080:localhost:3000 +``` + +This allows code running in the browser to access `localhost:8080` and reach your local development server. + +## Setup only + +Configure SSH on the VM without opening a connection: + +```bash +kernel browsers ssh --setup-only +``` + +This installs and configures the SSH server on the VM, then prints the manual connection command. Useful if you want to connect with your own SSH client or configuration. + +## Flags + +| Flag | Description | +|------|-------------| +| `-i, --identity ` | Path to SSH private key (generates ephemeral if not provided). | +| `-L, --local-forward ` | Local port forwarding (`localport:host:remoteport`). | +| `-R, --remote-forward ` | Remote port forwarding (`remoteport:host:localport`). | +| `--setup-only` | Setup SSH on VM without connecting. | diff --git a/docs.json b/docs.json index 805ef54..49ffe1a 100644 --- a/docs.json +++ b/docs.json @@ -81,6 +81,7 @@ "browsers/viewport", "browsers/profiles", "browsers/file-io", + "browsers/ssh", "browsers/computer-controls", "browsers/playwright-execution" ] diff --git a/reference/cli/browsers.mdx b/reference/cli/browsers.mdx index 38c1bc9..63e7345 100644 --- a/reference/cli/browsers.mdx +++ b/reference/cli/browsers.mdx @@ -44,6 +44,16 @@ Get detailed information about a browser session. |------|-------------| | `--output json`, `-o json` | Output raw JSON object. | +### `kernel browsers ssh ` +Open an interactive SSH session to a browser VM. Requires [websocat](https://github.com/vi/websocat) to be installed locally. + +| Flag | Description | +|------|-------------| +| `-i, --identity ` | Path to SSH private key (generates ephemeral if not provided). | +| `-L, --local-forward ` | Local port forwarding (`localport:host:remoteport`). | +| `-R, --remote-forward ` | Remote port forwarding (`remoteport:host:localport`). | +| `--setup-only` | Setup SSH on VM without connecting. | + ## Browser logs ### `kernel browsers logs stream ` From 1a6f40860166eb0700686e79e5fba110dbd90855 Mon Sep 17 00:00:00 2001 From: Steven Miller Date: Mon, 2 Feb 2026 14:30:01 -0500 Subject: [PATCH 2/4] Tabs for install --- browsers/ssh.mdx | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/browsers/ssh.mdx b/browsers/ssh.mdx index 08914a0..d6a3cc9 100644 --- a/browsers/ssh.mdx +++ b/browsers/ssh.mdx @@ -9,14 +9,19 @@ SSH into a running Kernel browser VM for debugging, running commands, or setting The `kernel browsers ssh` command requires [websocat](https://github.com/vi/websocat) to be installed locally: + + ```bash -# macOS brew install websocat - -# Linux -curl -fsSL https://github.com/vi/websocat/releases/download/v1.13.0/websocat.x86_64-unknown-linux-musl \ +``` + + +```bash +curl -fsSL https://github.com/vi/websocat/releases/download/v1.14.1/websocat.x86_64-unknown-linux-musl \ -o /usr/local/bin/websocat && chmod +x /usr/local/bin/websocat ``` + + ## Basic usage From 6c9dbd8c52a3edea447a3cee58429a441a93d200 Mon Sep 17 00:00:00 2001 From: Steven Miller Date: Mon, 2 Feb 2026 14:36:33 -0500 Subject: [PATCH 3/4] Add section about why it's cool --- browsers/ssh.mdx | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/browsers/ssh.mdx b/browsers/ssh.mdx index d6a3cc9..73428d8 100644 --- a/browsers/ssh.mdx +++ b/browsers/ssh.mdx @@ -5,6 +5,25 @@ description: "Open an interactive SSH session to a browser VM" SSH into a running Kernel browser VM for debugging, running commands, or setting up port forwarding. +## Forward local dev server to browser + +A common use case is exposing a local development server to the remote Kernel browser. This lets the browser access `localhost` URLs that point to your local machine: + +```bash +# 1. Start your local dev server (e.g., on port 3000) +npm run dev + +# 2. Create a browser with extended timeout +kernel browsers create --timeout 600 + +# 3. Forward your local server to the VM +# This exposes localhost:3000 on your machine as localhost:3000 inside the VM +kernel browsers ssh -R 3000:localhost:3000 + +# 4. In the browser's live view, navigate to: +# http://localhost:3000 +``` + ## Prerequisites The `kernel browsers ssh` command requires [websocat](https://github.com/vi/websocat) to be installed locally: From ec9ec25f592db7bb8869b7f95024fda021e2060c Mon Sep 17 00:00:00 2001 From: Steven Miller Date: Mon, 2 Feb 2026 16:00:13 -0500 Subject: [PATCH 4/4] Add note about timeout --- browsers/ssh.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/browsers/ssh.mdx b/browsers/ssh.mdx index 73428d8..5e6c1cf 100644 --- a/browsers/ssh.mdx +++ b/browsers/ssh.mdx @@ -24,6 +24,10 @@ kernel browsers ssh -R 3000:localhost:3000 # http://localhost:3000 ``` + +Kernel detects browser activity via WebRTC (live view) or CDP connections. SSH connections alone don't count as activity, so without `--timeout`, your browser may be cleaned up while you're connected via SSH. Either set a timeout or keep the [live view](/browsers/live-view) open. + + ## Prerequisites The `kernel browsers ssh` command requires [websocat](https://github.com/vi/websocat) to be installed locally: