Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 13 additions & 24 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,40 +2,35 @@

![ghostty](https://github.com/user-attachments/assets/aceee7eb-d57b-4d89-ac3d-ee1885d0187a)

`ghostty-web` is a fully-featured web terminal built on [Ghostty's](https://github.com/ghostty-org/ghostty)
terminal emulation core compiled to WebAssembly. By leveraging Ghostty's production-tested VT100 parser
and state machine, `ghostty-web` delivers fast, robust terminal emulation in the browser. For many use
cases it is a drop-in replacement for xterm.js.
`ghostty-web` is a web terminal developed for [mux](https://github.com/coder/mux) using
[mux](https://github.com/coder/mux) that leverages [Ghostty's](https://github.com/ghostty-org/ghostty)
terminal emulation core via WebAssembly. Because it leans on Ghostty to handle the complexity of terminal
emulation, `ghostty-web` can deliver fast, robust terminal emulation in the browser. The intent is
for this project to become a drop-in replacement for xterm.js. If it's not obvious, this repo is currently
under heavy development.

## Live Demo

Try ghostty-web instantly with:
Try ghostty-web yourself with:

```bash
npx @ghostty-web/demo
npx @ghostty-web/demo@next
```

This starts a local demo server with a real shell session. Works on Linux, macOS, and Windows.
This starts a local demo server with a real shell session. The demo server works best when run from Linux, but you can also try
it on macOS. Windows is not supported (yet). Chrome is the only supported browser at the moment.

<details>
<summary>Development setup (building from source)</summary>

> [!NOTE]
> Requires Zig and Bun, see [Development](#development)

```bash
git clone https://github.com/coder/ghostty-web
cd ghostty-web
bun install
bun run build # Builds the WASM module and library

# Terminal 1: Start PTY Server
cd demo
bun install
bun run dev

# Terminal 2: Start web server
bun run dev # http://localhost:8000/demo/
bun run demo:dev # http://localhost:8000/demo/
```

</details>
Expand Down Expand Up @@ -99,12 +94,6 @@ machine, and screen buffer) to WebAssembly, providing:
- Zero runtime dependencies (just ghostty-web + bundled WASM)
- Parser/state machine from Ghostty

## Why ghostty-web?

- **Don't reimplement VT100 parsing** – it's thousands of edge cases refined over years. Instead, leverage Ghostty's battle-tested terminal emulator that's proven by thousands of daily users.
- **Drop-in xterm.js replacement** – for many use cases, ghostty-web can replace xterm.js with minimal code changes
- **Modern & maintained** – Built on Ghostty, an actively developed modern terminal emulator, ensuring continued improvements and bug fixes.

## Usage Examples

### Basic Terminal
Expand Down Expand Up @@ -146,8 +135,8 @@ term.onData((data) => {

### Building WASM

`ghostty-web` builds a custom WASM binary from Ghostty's source with patches to expose additional
browser-specific functionality
`ghostty-web` builds a custom WASM binary from Ghostty's source with a patch to expose additional
functionality

```bash
bun run build
Expand Down
23 changes: 5 additions & 18 deletions demo/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,46 +5,33 @@ Cross-platform demo server for [ghostty-web](https://github.com/coder/ghostty-we
## Quick Start

```bash
npx @ghostty-web/demo
npx @ghostty-web/demo@next
```

This starts a local web server with a fully functional terminal connected to your shell.
Works on **Linux**, **macOS**, and **Windows**.
Works on **Linux** and **macOS** (no Windows support yet).

## What it does

- Starts an HTTP server on port 8080 (configurable via `PORT` env var)
- Starts a WebSocket server on port 3001 for PTY communication
- Opens a real shell session (bash, zsh, cmd.exe, or PowerShell)
- Opens a real shell session (bash, zsh, etc.)
- Provides full PTY support (colors, cursor positioning, resize, etc.)

## Usage

```bash
# Default (port 8080)
npx @ghostty-web/demo
npx @ghostty-web/demo@next

# Custom port
PORT=3000 npx @ghostty-web/demo
PORT=3000 npx @ghostty-web/demo@next
```

Then open http://localhost:8080 in your browser.

## Features

- 🖥️ Real shell sessions with full PTY support
- 🎨 True color (24-bit) and 256 color support
- ⌨️ Full keyboard support including special keys
- 📐 Dynamic terminal resizing
- 🔄 Auto-reconnection on disconnect
- 🌐 Cross-platform (Linux, macOS, Windows)

## Security Warning

⚠️ **This server provides full shell access.**

Only use for local development and demos. Do not expose to untrusted networks.

## License

MIT