ghostty-web

Install the ghostty-web package via npm to use the Ghostty terminal emulator in your web applications. It provides an xterm.js compatible API with a WASM-compiled parser from Ghostty.

npm install ghostty-web

To build the project from source, you must have Zig and Bun installed. This process builds from Ghostty's source using a patch to expose additional functionality.

bun run build

You can run a local demo that starts a loopback-only HTTP server with a real shell on http://127.0.0.1:8080 using npx.

Security Note: The demo starts a real local shell. Avoid remote exposure. The demo protects /ws with a per-run same-origin token and rejects cross-origin WebSocket handshakes.

Configuration:

• To bind to a different host, set HOST=<host>.
• If serving through extra hostnames or using a wildcard bind (e.g., HOST=0.0.0.0), you must also set GHOSTTY_ALLOWED_HOSTS=host1,host2.

npx @ghostty-web/demo@next

If you are serving the demo through an Nginx proxy, you must configure the Upgrade and Connection headers to support WebSockets. Ensure the Host header is passed through correctly.

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}

To start a local web server with a fully functional terminal connected to your shell, run the following command. This works on Linux and macOS (Windows is not yet supported).

Once running, open http://127.0.0.1:8080 in your browser.

npx @ghostty-web/demo@next

You can customize the server behavior using environment variables:

• PORT: Sets the HTTP server port (defaults to 8080).
• HOST: Sets the bind address (defaults to 127.0.0.1).
• GHOSTTY_ALLOWED_HOSTS: A comma-separated list of browser-visible hostnames allowed for WebSocket connections. This is required if you bind to a wildcard (like 0.0.0.0) or serve the demo through a different hostname.

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

# Explicit bind host and allowed hostnames
HOST=192.0.2.10 GHOSTTY_ALLOWED_HOSTS=demo.example npx @ghostty-web/demo@next

The FitAddon class provides automatic terminal resizing to fit its container element. It is compatible with the xterm.js FitAddon API. You can use it to manually trigger a fit or to automatically observe container resize events using a debounced ResizeObserver.

To use it, instantiate the addon, load it into your terminal instance, and call either fit() for manual resizing or observeResize() for automatic resizing. Always call dispose() when the terminal is destroyed to clean up the ResizeObserver and timers.

const fitAddon = new FitAddon();
term.loadAddon(fitAddon);
fitAddon.fit();              // Manual fit
fitAddon.observeResize();    // Auto-fit on resize

⚠️ Full Shell Access

This server provides full shell access to your machine. Use it only for local development and demos.

WebSocket Security

• The server protects the /ws endpoint with a per-run same-origin token fetched from /api/token.
• The server rejects WebSocket handshakes if the token is missing, if the Host is not allowed, or if the WebSocket Origin does not match the request host.
• Warning: Do not set permissive CORS in front of the /api/token endpoint.

The ghostty-web API is designed to be compatible with xterm.js. To use it, you must first call init() to initialize the WASM environment, then instantiate a Terminal object. You can then attach the terminal to a DOM element and handle data via onData and write methods.

import { init, Terminal } from 'ghostty-web';

await init();

const term = new Terminal({
  fontSize: 14,
  theme: {
    background: '#1a1b26',
    foreground: '#a9b1d6',
  },
});

term.open(document.getElementById('terminal'));
term.onData((data) => websocket.send(data));
websocket.onmessage = (e) => term.write(e.data);

Use the ITerminalOptions interface to configure the terminal instance. It supports standard terminal settings like dimensions, cursor styles, and fonts, as well as Ghostty-specific features like EOL conversion and smooth scrolling.

Available Options:

• cols (number, default: 80)
• rows (number, default: 24)
• cursorBlink (boolean, default: false)
• cursorStyle ('block' | 'underline' | 'bar')
• theme (ITheme)
• scrollback (number, default: 10000)
• fontSize (number, default: 15)
• fontFamily (string, default: 'monospace')
• allowTransparency (boolean)
• convertEol (boolean, default: false): Converts \n to \r\n.
• disableStdin (boolean, default: false): Disables keyboard input.
• smoothScrollDuration (number, default: 100): Duration in ms for smooth scroll animation (0 for instant).

The ITheme interface allows you to customize the terminal's visual appearance, including foreground, background, cursor, and the 16 ANSI colors (0-15).

Key Properties:

• foreground, background, cursor, cursorAccent
• selectionBackground, selectionForeground
• ANSI Colors: black, red, green, yellow, blue, magenta, cyan, white, and their bright counterparts (e.g., brightBlack, brightRed).