Documentation

Remote terminal access from any browser. One command to start, a WebSocket to connect.

Quick Start

Start a walkie-talkie server with a single command. No install required — npx handles everything.

terminal
npx @walkie-talkie/cli@latest --open

This starts a server on port 3456, generates a one-time token, and opens the web client in your browser. You can also scan the QR code from a phone or tablet.

Install

If you prefer a permanent install:

terminal
npm install -g @walkie-talkie/cli

Then run:

terminal
walkie-talkie --open

Packages

Walkie-talkie is a monorepo with modular packages. Use only what you need.

PackageDescription
@walkie-talkie/serverExpress + WebSocket server with node-pty terminals
@walkie-talkie/clientFramework-agnostic TypeScript WebSocket client
@walkie-talkie/reactReact hooks and xterm.js TerminalView component
@walkie-talkie/sharedProtocol types and constants shared between packages
@walkie-talkie/cliCLI launcher — the npx entry point

How It Works

The server spawns real pseudo-terminals using node-pty and bridges them to the browser over WebSocket. The flow:

  1. Server starts — listens on a port (default 3456) and generates a short-lived token.
  2. Client connects — opens a WebSocket to ws://host:3456/ws and sends the token to authenticate.
  3. Session established — the server issues a session ID. The client can now create terminals, send input, and receive output.
  4. Real-time I/O — keystrokes flow from browser to PTY, output flows back. Resize events keep the terminal dimensions in sync.
Security model: Tokens are single-use and expire after 5 minutes. Sessions persist across reconnects (stored at ~/.walkie-talkie/sessions.json) but tokens are never saved to disk.

Minimal Example

Connect to a walkie-talkie server from any WebSocket client:

raw-websocket.ts
const ws = new WebSocket('ws://localhost:3456/ws');

ws.onopen = () => {
  // Authenticate with a one-time token
  ws.send(JSON.stringify({ type: 'auth', token: 'your-token' }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);

  switch (msg.type) {
    case 'auth:ok':
      // Authenticated — create a terminal
      ws.send(JSON.stringify({
        type: 'terminal:create',
        cols: 80,
        rows: 24,
      }));
      break;

    case 'terminal:created':
      console.log('Terminal spawned:', msg.terminal.id);
      // Send a command
      ws.send(JSON.stringify({
        type: 'terminal:input',
        terminalId: msg.terminal.id,
        data: 'echo hello\n',
      }));
      break;

    case 'terminal:output':
      process.stdout.write(msg.data);
      break;
  }
};

Or use the TypeScript client for a higher-level API with auto-reconnect, session persistence, and state management.

Source Code

Walkie-talkie is open source under the MIT license.

github.com/vochsel/walkie-talkie
NextCLI Reference →