From e5265a738c25f9acea8e650d55ded7330479c2a1 Mon Sep 17 00:00:00 2001 From: Shivang Date: Tue, 9 Jun 2026 00:25:11 -0700 Subject: [PATCH] docs: cool README hero + document session sharing & Remote MCP MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README: centered logo/tagline/badges hero + a Fast/Share/MCP/Embed pillars table; add Session Sharing, Remote Control, AI/MCP, Embeddable to Features; new "Session Sharing" section; a Remote MCP note in the MCP section; link the new sharing guide. - docs/session-sharing.md (new): full guide โ€” scopes, view/control + approval, LAN/Tailscale/Cloudflare reach (pre-warm/keep-warm), the mobile web viewer, the native remote client, Remote MCP, the end-to-end encryption design, a settings reference, and troubleshooting. - docs/mcp-server.md: "Remote MCP (over a shared session)" subsection. - wiki: new Session-Sharing page, a "Sharing & AI" sidebar group, links from Home + Features, and a Remote-MCP note on the MCP page. Generated with [Claude Code](https://claude.com/claude-code) --- README.md | 51 +++++++++- docs/mcp-server.md | 16 +++ docs/session-sharing.md | 191 +++++++++++++++++++++++++++++++++++ docs/wiki/Features.md | 15 +++ docs/wiki/Home.md | 1 + docs/wiki/MCP-Server.md | 10 ++ docs/wiki/Session-Sharing.md | 104 +++++++++++++++++++ docs/wiki/_Sidebar.md | 6 +- 8 files changed, 391 insertions(+), 3 deletions(-) create mode 100644 docs/session-sharing.md create mode 100644 docs/wiki/Session-Sharing.md diff --git a/README.md b/README.md index e1273560..00803489 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,23 @@ +
+ +BossTerm + # BossTerm +**A blazing-fast terminal you can embed, share to any device, and hand to your AI.** + [![CI](https://github.com/kshivang/BossTerm/actions/workflows/test.yml/badge.svg)](https://github.com/kshivang/BossTerm/actions/workflows/test.yml) [![Release](https://github.com/kshivang/BossTerm/actions/workflows/release.yml/badge.svg)](https://github.com/kshivang/BossTerm/releases) [![Download DMG](https://img.shields.io/github/v/release/kshivang/BossTerm?label=Download%20DMG&logo=apple)](https://github.com/kshivang/BossTerm/releases/latest) [![Maven Central](https://img.shields.io/maven-central/v/com.risaboss/bossterm-core)](https://central.sonatype.com/namespace/com.risaboss) -A modern terminal emulator built with **Kotlin** and **Compose Desktop**. +
-BossTerm is a high-performance terminal emulator designed for developers who want a fast, customizable, and feature-rich terminal experience on macOS, Linux, and Windows. +| โšก [**Fast**](#performance) | ๐Ÿ“ฑ [**Share**](#session-sharing) | ๐Ÿค– [**MCP for AI**](#bossterm-mcp) | ๐Ÿงฉ [**Embeddable**](#embedding-in-your-app) | +|:--:|:--:|:--:|:--:| +| 1,645 MB/s โ€” edges out Alacritty | Watch & control from any device | Expose tabs to Claude Code & co. | Drop it into your Compose app | + +A modern terminal emulator built with **Kotlin** and **Compose Desktop** โ€” high-performance, deeply customizable, and feature-rich on macOS, Linux, and Windows. ## Performance @@ -206,6 +216,10 @@ cd BossTerm - **Debug Tools** - Built-in terminal debugging with Ctrl+Shift+D - **Welcome Wizard** - First-time setup wizard for shell, tools, and AI assistants - **Customizable** - JSON-based settings at `~/.bossterm/settings.json` +- **Session Sharing** - Watch or control a tab / window / all windows from any device โ€” self-hosted, with a QR code and a mobile-friendly web viewer (LAN, Tailscale, or a zero-config Cloudflare tunnel) +- **Remote Control** - End-to-end encrypted; viewers get typing access on approval, or connect from another BossTerm as a native remote client +- **AI / MCP Server** - Built-in [Model Context Protocol](https://modelcontextprotocol.io) server exposes your terminals to Claude Code, Codex, Gemini CLI, and OpenCode +- **Embeddable** - Drop the terminal into your own Kotlin/Compose Desktop app as a library (`com.risaboss:bossterm-compose`) ## Keyboard Shortcuts @@ -455,6 +469,35 @@ fun MyApp() { } ``` +## Session Sharing + +Watch โ€” or hand over โ€” a live terminal to any device, with **no cloud relay and no account**. +BossTerm runs the share server itself; viewers open a link (or scan a QR code) in any browser, or +connect from another BossTerm as a native client. + +- **Scope**: share a single **tab** (with its splits), a whole **window**, or **all windows** + (viewers see tabs grouped by window). +- **View or Control**: hand out a read-only **view** link or a **control** link (typing access). + View-only viewers can request control mid-session and you approve from a prompt โ€” required for + public links by default, skipped on the LAN. +- **Reach**: LAN out of the box, or a public URL via **Tailscale** (Serve/Funnel) or a zero-config + **Cloudflare** quick tunnel (the default โ€” `cloudflared` is fetched automatically, no account). + The tunnel is pre-warmed so the QR is ready the moment you hit Share. +- **Mobile web viewer**: xterm.js-based and touch-tuned โ€” soft-keyboard push, an on-screen key bar + (Esc / Tab / Ctrl / arrows + a โŒจ toggle), pinch-zoom, fit-to-screen, and clickable links. +- **Native remote client**: "Add remote" in BossTerm to mirror another machine's shared tabs into + your own window โ€” including its **Remote MCP** โ€” with control relayed up the chain. +- **End-to-end encrypted**: the session key rides in the URL **fragment** (`#k=โ€ฆ`), which browsers + never send to the server โ€” so even a tunnel relay can't read your session. Frames use + per-connection AES-256-GCM, and a short verification code lets both ends confirm the same key. + +Enable it under **Settings โ†’ Session Sharing** (off by default), then **Share** from a tab's menu. +Defaults: binds the LAN on port `7677`, Cloudflare remote mode, approval required only for public +links. + +See **[docs/session-sharing.md](docs/session-sharing.md)** for the full guide โ€” scopes, +remote-access setup, the viewer, the native client, the encryption design, and every setting. + ## BossTerm MCP BossTerm ships an in-process [Model Context Protocol](https://modelcontextprotocol.io) @@ -471,6 +514,9 @@ code (`run_command` โ€” recommended default shell for AI clients). `Host` headers (DNS-rebinding defense). Any local process running as your user can reach it while it is enabled. - **Opt-in**: disabled by default. Toggle on under Settings โ†’ BossTerm MCP. +- **Remote MCP**: when you [share a session](#session-sharing), the host's MCP can be driven from + the web viewer (an "MCP pill" toggles it and attaches CLIs) or from a native remote client โ€” + calls on shared tabs are relayed to the host. ### Turning it on (as a user) @@ -599,6 +645,7 @@ Run `man bossterm` after installation for the complete reference. - [Embedding Guide](docs/embedding.md) - Embed a single terminal with custom context menus - [Tabbed Terminal Guide](docs/tabbed-terminal.md) - Full-featured tabbed terminal with splits +- [Session Sharing](docs/session-sharing.md) - Watch & control a terminal from any device (web viewer, QR, tunnels, E2E) - [BossTerm MCP Server](docs/mcp-server.md) - Expose tabs to MCP clients (Claude Code, Codex, Gemini, OpenCode) - [BossTerm CLI](docs/bossterm.1) - `man bossterm` reference (troff) - [Onboarding Wizard](docs/onboarding.md) - First-time setup wizard for users diff --git a/docs/mcp-server.md b/docs/mcp-server.md index ecf293fa..a685ac1c 100644 --- a/docs/mcp-server.md +++ b/docs/mcp-server.md @@ -505,6 +505,22 @@ under the button. **Codex caveat**: registration succeeds with codex-cli 0.130, but Codex currently speaks streamable HTTP only, so the runtime connection will fail against the SSE endpoint until BossTerm's MCP SDK is upgraded. +## Remote MCP (over a shared session) + +The MCP server is loopback-only, but [session sharing](session-sharing.md) carries it to remote +devices. When a window with MCP enabled is shared: + +- The web viewer shows an **MCP pill** that mirrors the host's MCP state; from it a viewer can + toggle the server and attach AI CLIs โ€” the operations execute on the **host**, not the viewer. +- MCP tool calls against shared tabs are **relayed to the host's** MCP server, using the host's + configured `serverName` and bound port. +- A native "Add remote" BossTerm client surfaces the same control as **Remote MCP** in the remote + tab group. + +This lets a phone or a second machine drive the host's terminals through an AI client over the +shared session, without exposing the loopback endpoint directly. See +[docs/session-sharing.md](session-sharing.md#remote-mcp) for the sharing side. + ## Using as Claude Code's default shell > **Opt-in.** `run_command` is exposed by default, but the agent only uses it diff --git a/docs/session-sharing.md b/docs/session-sharing.md new file mode 100644 index 00000000..86a22bb8 --- /dev/null +++ b/docs/session-sharing.md @@ -0,0 +1,191 @@ +# Session Sharing + +BossTerm can share a live terminal with another device โ€” to **watch** it, or to **control** it โ€” +without any cloud relay or account. Your machine *is* the server: BossTerm runs a small embedded +web server, serves an [xterm.js](https://xtermjs.org)-based viewer over a WebSocket, and other +devices reach it over your LAN or through a tunnel. The session key never leaves the URL fragment, +so even a public tunnel relay can't read your session. + +> Session sharing is **off by default**. Turn it on under **Settings โ†’ Session Sharing**, then +> use **Share** from a tab's menu. + +--- + +## Table of contents + +- [What you can share (scopes)](#what-you-can-share-scopes) +- [View vs. control](#view-vs-control) +- [Reach: LAN, Tailscale, Cloudflare](#reach-lan-tailscale-cloudflare) +- [Starting a share](#starting-a-share) +- [The web viewer](#the-web-viewer) +- [The native "Add remote" client](#the-native-add-remote-client) +- [Remote MCP](#remote-mcp) +- [Security & end-to-end encryption](#security--end-to-end-encryption) +- [Settings reference](#settings-reference) +- [Troubleshooting](#troubleshooting) + +--- + +## What you can share (scopes) + +Pick a scope in the Share dialog โ€” you can switch it live: + +| Scope | Shares | Notes | +|-------|--------|-------| +| **Tab** | The selected tab and its splits | The default. | +| **Window** | Every tab of the window that owns the tab | Reacts to tabs opening/closing; viewers switch tabs themselves. | +| **All windows** | Every tab of every BossTerm window | Reacts to windows opening/closing; the viewer groups tabs by window. | + +Splits are preserved: a viewer sees the same pane layout, and on a phone the splits collapse into +swipeable sub-tabs. + +## View vs. control + +Each share produces **two links** (and two QR codes): + +- **View** โ€” read-only. The viewer sees output but can't type. +- **Control** โ€” typing access: input, opening/closing tabs and splits, launching AI assistants, + renaming, etc. + +A view-only viewer can **request control** mid-session; you get an approval prompt and can grant or +deny. Whether *connecting* needs approval at all is governed by +[`sessionSharingApprovalScope`](#settings-reference): + +- `funnel` (default) โ€” approval is required only for **public** links (a Cloudflare/Tailscale + Funnel tunnel or a custom public URL); LAN/loopback is trusted and connects without a prompt. +- `all` โ€” always require approval. +- `off` โ€” never prompt. + +When you approve a device it receives a rolling 24-hour access key, so reconnects from the same +device skip the prompt. Granting control to a view-only viewer is remembered the same way. + +## Reach: LAN, Tailscale, Cloudflare + +How the viewer URL is produced is set by **`shareTailscaleMode`** (Settings โ†’ Session Sharing โ†’ +Remote Access, also switchable live in the Share dialog): + +| Mode | Reach | URL | Needs | +|------|-------|-----|-------| +| `off` | Your local network | `http://:7677/โ€ฆ` | Nothing โ€” works out of the box | +| `serve` | Your Tailscale tailnet | `https://.ts.net/โ€ฆ` | Tailscale + MagicDNS/HTTPS | +| `funnel` | Public internet | `https://.ts.net/โ€ฆ` | Tailscale Funnel enabled | +| `cloudflare` | Public internet | `https://.trycloudflare.com/โ€ฆ` | **Nothing โ€” the default** | + +**Cloudflare** is the default: BossTerm downloads `cloudflared` for you on first use (no account, no +config) and opens a quick tunnel. Each session gets a fresh random hostname. To make the QR appear +instantly, the tunnel is **pre-warmed** at startup (when sharing is enabled with a remote provider) +and **kept warm** across re-shares โ€” so the verified public URL is already published by the time you +open the Share dialog. Disabling sharing, switching the mode to `off`, or quitting tears the tunnel +down. + +If you front the server with your own reverse proxy, set +[`sessionSharingPublicUrl`](#settings-reference) and that URL is advertised instead. + +## Starting a share + +1. Enable sharing once: **Settings โ†’ Session Sharing โ†’ Enable**. +2. Right-click a tab (or use the Tab menu) โ†’ **Share tab / Share window / Share all windows**. +3. The Share dialog opens with: + - an editable **session name** (defaults to `you_your-machine`), + - the **QR code** with a **View / Control** toggle and copyable links, + - the **scope** picker (Tab / Window / All windows), + - the **remote-access** mode and its status. +4. Scan the QR or send the link. On another device it opens the [web viewer](#the-web-viewer); in + another BossTerm it can be dialed with [Add remote](#the-native-add-remote-client). + +A small indicator in the tab bar shows while you're sharing (toggle with +`sessionSharingShowIndicator`). + +## The web viewer + +The viewer is plain xterm.js served from the share server โ€” it runs in any modern browser +(Chrome, Safari, Firefox, Edge; iOS and Android included) with nothing to install. It's tuned for +phones: + +- **Soft keyboard** โ€” the view lifts so the cursor stays visible above the keyboard, and the + keyboard stays up while a TUI streams output. +- **On-screen key bar** โ€” Esc, Tab, Enter, Ctrl combos and arrows, plus a **โŒจ toggle** to show/hide + the soft keyboard. +- **Touch** โ€” drag to scroll (including inside mouse-reporting TUIs), pinch to zoom, and a + fit-to-screen mode so the whole grid fits without horizontal panning. +- **Links** โ€” URLs are clickable; text selection works by touch. +- **Tabs & splits** โ€” switch tabs and panes from chips; drag split dividers to resize (with + control). +- **Status** โ€” a presence badge (viewer count), the terminal size, an end-to-end verification code, + and an **MCP pill** (see [Remote MCP](#remote-mcp)). + +## The native "Add remote" client + +Another BossTerm can connect to a share as a first-class client instead of a browser: + +- **Add remote** โ†’ paste a share link. The host's shared tabs mirror into your window as remote + tabs, grouped by window when the host shared "all windows" (e.g. `Window 2 โ€บ Tab 3 (via host)`). +- Control requests relay **up the chain**: viewer โ†’ host โ†’ the host's own upstream, so you can steer + a session two hops away (each host approves in turn). +- A client refuses to add a link that points back at its own shares (no mirror loops). + +## Remote MCP + +If the host has the [BossTerm MCP server](mcp-server.md) running, sharing carries it along: + +- The viewer shows an **MCP pill** reflecting the host's MCP state; from it you can toggle the + server and attach AI CLIs โ€” the actions run on the host. +- MCP tool calls against shared tabs are **relayed to the host's** MCP server, using the host's + configured server name and port. + +This lets a phone or a second machine point an AI client at the host's terminals through the same +shared session. + +## Security & end-to-end encryption + +- **The key never reaches the server.** The per-share session secret (32 random bytes) is placed in + the URL **fragment** โ€” `โ€ฆ/?t=#k=`. Browsers never transmit the part after `#`, so + no server or tunnel relay (Cloudflare, Tailscale) ever sees it. +- **Per-connection keys.** Client and host exchange random salts (in the clear โ€” useless on their + own) and derive a fresh AES-256-GCM key with HKDF-SHA256. Every frame is encrypted; a direction + byte is mixed in as additional data so frames can't be reflected back. +- **Verification code.** The Share dialog and the viewer each show a short code (the first 4 bytes + of `SHA-256(secret)`, as 8 hex digits). If they match, both ends hold the same untampered key. +- **Tokens.** View and control are **separate bearer tokens**, so you can hand out read-only access + without exposing control, and revoke one role independently of the key. +- **Trusted hosts.** Loopback and private addresses (`127.0.0.1`, `10.*`, `192.168.*`, + `172.16โ€“31.*`, `169.254.*`, `*.local`, `*.ts.net`) are treated as private. Plaintext links are + allowed only there; any `https`/tunnel link is end-to-end encrypted. An old plaintext-only client + connecting to a public tunnel is rejected with an "update BossTerm" message. + +## Settings reference + +All under **Settings โ†’ Session Sharing**, persisted in `~/.bossterm/settings.json`: + +| Setting | Default | Meaning | +|---------|---------|---------| +| `sessionSharingEnabled` | `false` | Master switch. Off โ‡’ sharing isn't offered and any tunnel is torn down. | +| `sessionSharingPort` | `7677` | TCP port for the share server. If busy, it tries the next free port. | +| `sessionSharingBind` | `"lan"` | `"lan"` (bind `0.0.0.0`), `"loopback"` (`127.0.0.1` only), or `"custom"`. | +| `sessionSharingBindHost` | `""` | Host to bind when `sessionSharingBind` is `"custom"` (blank โ‡’ `127.0.0.1`). | +| `shareTailscaleMode` | `"cloudflare"` | Remote-access provider: `"off"`, `"serve"`, `"funnel"`, `"cloudflare"`. | +| `sessionSharingPublicUrl` | `""` | Advertise this URL instead of the bound/tunnel URL (for a custom proxy). | +| `sessionSharingApprovalScope` | `"funnel"` | Require join approval: `"all"`, `"off"`, or `"funnel"` (only for public links). | +| `sessionSharingShowIndicator` | `true` | Show the sharing indicator in the tab bar. | + +> Note `shareTailscaleMode` defaults to `cloudflare`, but sharing is still gated by +> `sessionSharingEnabled` (off by default) โ€” so no tunnel opens until you turn sharing on. + +## Troubleshooting + +- **QR/link opens "tunnel error" or a blank page** โ€” give the Cloudflare tunnel a moment on the + very first share (it downloads `cloudflared` once). Use **Refresh link** in the dialog to spin a + fresh tunnel. Quick-tunnel hostnames are ephemeral; a new one is minted each session. +- **Viewer says "Forbidden"** โ€” the link is pointing at the wrong local service. Re-open the Share + dialog and use its current link/QR (it always reflects the live tunnel). +- **Can't connect on the LAN** โ€” confirm both devices are on the same network and your firewall + allows inbound on `sessionSharingPort` (7677). Check `sessionSharingBind` is `"lan"`, not + `"loopback"`. +- **Tailscale modes do nothing** โ€” ensure `tailscale` is installed and signed in; Funnel needs to be + enabled for the node, and Serve needs MagicDNS/HTTPS certificates. +- **Verification codes differ** โ€” do **not** trust the session; the relay or link may be tampered. + Regenerate the link. +- **Phone keyboard hides the input in a TUI** โ€” tap the **โŒจ** key-bar button to toggle the keyboard; + the view re-aligns the cursor above it. + +See also: [BossTerm MCP Server](mcp-server.md) ยท [Troubleshooting](troubleshooting.md). diff --git a/docs/wiki/Features.md b/docs/wiki/Features.md index 4dbd6854..a67a7ba3 100644 --- a/docs/wiki/Features.md +++ b/docs/wiki/Features.md @@ -89,6 +89,21 @@ BossTerm is packed with features for modern terminal workflows. --- +## Sharing & AI + +| Feature | Description | +|---------|-------------| +| **Session Sharing** | Watch or control a tab / window / all windows from any device โ€” self-hosted, no cloud relay | +| **Web Viewer** | Mobile-friendly xterm.js viewer over LAN, Tailscale, or a zero-config Cloudflare tunnel, with a QR code | +| **Remote Control** | View-only or full typing access on approval; connect from another BossTerm as a native client | +| **End-to-End Encryption** | Per-connection AES-256-GCM; the key rides the URL fragment and never reaches the relay | +| **BossTerm MCP** | Built-in Model Context Protocol server exposes tabs to Claude Code, Codex, Gemini, OpenCode | +| **Remote MCP** | Drive the host's MCP from a shared web viewer or native remote client | + +See [[Session-Sharing]] and [[MCP-Server]] for details. + +--- + ## See Also - [[Keyboard-Shortcuts]] - Full shortcut reference diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md index e6f24af5..2fdd6b25 100644 --- a/docs/wiki/Home.md +++ b/docs/wiki/Home.md @@ -13,6 +13,7 @@ Welcome to the **BossTerm** wiki! BossTerm is a modern, high-performance termina | [[Configuration]] | Settings and customization options | | [[Keyboard-Shortcuts]] | Full keyboard shortcut reference | | [[Shell-Integration]] | OSC 7 and OSC 133 shell setup | +| [[Session-Sharing]] | Watch & control a terminal from any device (web viewer, QR, tunnels, E2E) | --- diff --git a/docs/wiki/MCP-Server.md b/docs/wiki/MCP-Server.md index 83250dff..103bf881 100644 --- a/docs/wiki/MCP-Server.md +++ b/docs/wiki/MCP-Server.md @@ -369,6 +369,16 @@ upgraded. --- +## Remote MCP (over a shared session) + +The MCP server is loopback-only, but [[Session Sharing|Session-Sharing]] carries it to remote +devices. When a window with MCP enabled is shared, the web viewer shows an **MCP pill** that +mirrors and toggles the host's MCP (and attaches AI CLIs, executed on the host), and MCP tool +calls against shared tabs are **relayed to the host's** server using its configured name and port. +A native "Add remote" BossTerm client surfaces the same control as **Remote MCP**. + +--- + ## Settings reference All MCP-related fields are persisted to `~/.bossterm/settings.json`. diff --git a/docs/wiki/Session-Sharing.md b/docs/wiki/Session-Sharing.md new file mode 100644 index 00000000..dcedfcb6 --- /dev/null +++ b/docs/wiki/Session-Sharing.md @@ -0,0 +1,104 @@ +# Session Sharing + +BossTerm can share a live terminal with another device โ€” to **watch** it or to **control** it โ€” +with **no cloud relay and no account**. Your machine is the server: BossTerm runs a small embedded +web server, serves an [xterm.js](https://xtermjs.org) viewer over a WebSocket, and other devices +reach it over your LAN or through a tunnel. The session key never leaves the URL fragment, so even +a public tunnel relay can't read your session. + +> Session sharing is **off by default**. Turn it on under **Settings โ†’ Session Sharing**, then use +> **Share** from a tab's menu. + +--- + +## What you can share + +| Scope | Shares | +|-------|--------| +| **Tab** | The selected tab and its splits (the default) | +| **Window** | Every tab of the owning window (viewers switch tabs themselves) | +| **All windows** | Every tab of every window, grouped by window in the viewer | + +## View vs. control + +Each share produces a read-only **view** link and a **control** link (typing access) โ€” each with +its own QR code. A view-only viewer can **request control** mid-session; you approve from a prompt. +Whether *connecting* needs approval is set by `sessionSharingApprovalScope`: + +- `funnel` (default) โ€” approval only for **public** links; LAN/loopback is trusted. +- `all` โ€” always require approval. +- `off` โ€” never prompt. + +Approved devices get a rolling 24-hour access key, so reconnects skip the prompt. + +## Reach: LAN, Tailscale, Cloudflare + +Set by `shareTailscaleMode` (Settings โ†’ Session Sharing โ†’ Remote Access; also switchable in the +Share dialog): + +| Mode | Reach | URL | Needs | +|------|-------|-----|-------| +| `off` | Local network | `http://:7677/โ€ฆ` | Nothing | +| `serve` | Tailscale tailnet | `https://.ts.net/โ€ฆ` | Tailscale + HTTPS | +| `funnel` | Public internet | `https://.ts.net/โ€ฆ` | Tailscale Funnel | +| `cloudflare` | Public internet | `https://.trycloudflare.com/โ€ฆ` | **Nothing โ€” default** | + +**Cloudflare** is the default: `cloudflared` is fetched automatically (no account), and the tunnel +is **pre-warmed** at startup and **kept warm** across re-shares, so the QR is ready the moment you +hit Share. Set `sessionSharingPublicUrl` to advertise your own reverse-proxy URL instead. + +## The web viewer + +Plain xterm.js in any modern browser (iOS/Android included), tuned for touch: + +- Soft-keyboard push (cursor stays visible; keyboard stays up during TUI output) +- On-screen key bar โ€” Esc / Tab / Enter / Ctrl / arrows + a **โŒจ toggle** +- Drag-to-scroll (even inside TUIs), pinch-zoom, fit-to-screen +- Clickable links, touch selection +- Tab/split switching, presence badge, terminal size, E2E verification code, and an **MCP pill** + +## Native "Add remote" client + +Another BossTerm can dial a share with **Add remote**: the host's shared tabs mirror into your +window (grouped by window for "all windows" shares). Control relays **up the chain** +(viewer โ†’ host โ†’ its upstream), and a client won't add a link pointing back at its own shares. + +## Remote MCP + +If the host runs the [[BossTerm MCP Server|MCP-Server]], sharing carries it: the viewer's **MCP +pill** toggles the host's server and attaches AI CLIs (executed on the host), and MCP tool calls on +shared tabs are relayed to the host's MCP server. The native remote client surfaces this as +**Remote MCP**. + +## Security & end-to-end encryption + +- **The key never reaches the server** โ€” the per-share secret rides in the URL **fragment** + (`โ€ฆ/?t=#k=`), which browsers never transmit. No tunnel relay sees it. +- **Per-connection keys** โ€” client and host exchange salts and derive a fresh AES-256-GCM key via + HKDF-SHA256; every frame is encrypted, with a direction byte as additional data. +- **Verification code** โ€” both ends show a short code (first 4 bytes of `SHA-256(secret)`); matching + codes confirm the same untampered key. +- **Separate view/control bearer tokens**, revocable per role. +- **Trusted hosts** โ€” loopback and private ranges (`10.*`, `192.168.*`, `172.16โ€“31.*`, `*.local`, + `*.ts.net`) allow plaintext; any `https`/tunnel link is end-to-end encrypted. + +## Settings reference + +| Setting | Default | Meaning | +|---------|---------|---------| +| `sessionSharingEnabled` | `false` | Master switch; off tears down any tunnel | +| `sessionSharingPort` | `7677` | Share-server port (tries the next free one if busy) | +| `sessionSharingBind` | `"lan"` | `"lan"` (0.0.0.0), `"loopback"`, or `"custom"` | +| `sessionSharingBindHost` | `""` | Host for `"custom"` bind | +| `shareTailscaleMode` | `"cloudflare"` | `"off"`, `"serve"`, `"funnel"`, `"cloudflare"` | +| `sessionSharingPublicUrl` | `""` | Advertise this URL instead (custom proxy) | +| `sessionSharingApprovalScope` | `"funnel"` | `"all"`, `"off"`, or `"funnel"` (public only) | +| `sessionSharingShowIndicator` | `true` | Show the sharing indicator in the tab bar | + +## See Also + +- [[BossTerm MCP Server|MCP-Server]] - Expose tabs to AI clients +- [[Configuration]] - All settings +- [[Troubleshooting]] - Common issues + +> Full guide: [docs/session-sharing.md](https://github.com/kshivang/BossTerm/blob/master/docs/session-sharing.md) diff --git a/docs/wiki/_Sidebar.md b/docs/wiki/_Sidebar.md index a8ebdf2f..0af9d3ac 100644 --- a/docs/wiki/_Sidebar.md +++ b/docs/wiki/_Sidebar.md @@ -11,11 +11,15 @@ - [[Keyboard Shortcuts|Keyboard-Shortcuts]] - [[Shell Integration|Shell-Integration]] +### Sharing & AI + +- [[Session Sharing|Session-Sharing]] +- [[BossTerm MCP Server|MCP-Server]] + ### Embedding - [[Embedding Guide|Embedding-Guide]] - [[Tabbed Terminal Guide|Tabbed-Terminal-Guide]] -- [[BossTerm MCP Server|MCP-Server]] - [[API Reference|API-Reference]] ### Help