node-pty

forkpty(3) bindings for node.js. This allows you to fork processes with pseudoterminal file descriptors. It returns a terminal object which allows reads and writes.

This is useful for:

• Writing a terminal emulator (eg. via xterm.js).
• Getting certain programs to think you're a terminal, such as when you need a program to send you control sequences.

node-pty supports Linux, macOS and Windows. Windows support is possible by utilizing the Windows conpty API on Windows 1809+ and the winpty library in older version.

Real-world Uses

node-pty powers many different terminal emulators, including:

• Microsoft Visual Studio Code
• Hyper
• Upterm
• Script Runner for Atom.
• Theia
• FreeMAN file manager
• terminus - An Atom plugin for providing terminals inside your Atom workspace.
• x-terminal - Also an Atom plugin that provides terminals inside your Atom workspace.
• Termination - Also an Atom plugin that provides terminals inside your Atom workspace.
• atom-xterm - Also an Atom plugin that provides terminals inside your Atom workspace.
• electerm Terminal/SSH/SFTP client(Linux, macOS, Windows).
• Extraterm
• Wetty Browser based Terminal over HTTP and HTTPS
• nomad

Do you use node-pty in your application as well? Please open a Pull Request to include it here. We would love to have it in our list.

Example Usage

var os = require('os');
var pty = require('node-pty');

var shell = os.platform() === 'win32' ? 'powershell.exe' : 'bash';

var ptyProcess = pty.spawn(shell, [], {
  name: 'xterm-color',
  cols: 80,
  rows: 30,
  cwd: process.env.HOME,
  env: process.env
});

ptyProcess.on('data', function(data) {
  process.stdout.write(data);
});

ptyProcess.write('ls\r');
ptyProcess.resize(100, 40);
ptyProcess.write('ls\r');

Building

# Install dependencies and build C++
npm install
# Compile TypeScript -> JavaScript
npm run tsc

Dependencies

Linux/Ubuntu

sudo apt install -y make python build-essential

The following are also needed:

• Node.JS 10+

Windows

npm install requires some tools to be present in the system like Python and C++ compiler. Windows users can easily install them by running the following command in PowerShell as administrator. For more information see https://github.com/felixrieseberg/windows-build-tools:

npm install --global --production windows-build-tools

The following are also needed:

• Windows SDK - only the "Desktop C++ Apps" components are needed to be installed
• Node.JS 10+

Debugging

The wiki contains instructions for debugging node-pty.

Security

All processes launched from node-pty will launch at the same permission level of the parent process. Take care particularly when using node-pty inside a server that's accessible on the internet. We recommend launching the pty inside a container to protect your host machine.

Thread Safety

Note that node-pty is not thread safe so running it across multiple worker threads in node.js could cause issues.

Flow Control

Automatic flow control can be enabled by either providing handleFlowControl = true in the constructor options or setting it later on:

const PAUSE = '\x13';   // XOFF
const RESUME = '\x11';  // XON

const ptyProcess = pty.spawn(shell, [], {handleFlowControl: true});

// flow control in action
ptyProcess.write(PAUSE);  // pty will block and pause the slave program
...
ptyProcess.write(RESUME); // pty will enter flow mode and resume the slave program

// temporarily disable/re-enable flow control
ptyProcess.handleFlowControl = false;
...
ptyProcess.handleFlowControl = true;

By default PAUSE and RESUME are XON/XOFF control codes (as shown above). To avoid conflicts in environments that use these control codes for different purposes the messages can be customized as flowControlPause: string and flowControlResume: string in the constructor options. PAUSE and RESUME are not passed to the underlying pseudoterminal if flow control is enabled.

Troubleshooting

Powershell gives error 8009001d

> Internal Windows PowerShell error. Loading managed Windows PowerShell failed with error 8009001d.

This happens when PowerShell is launched with no SystemRoot environment variable present.

ConnectNamedPipe failed: Windows error 232

This error can occur due to anti-virus software intercepting winpty from creating a pty. To workaround this you can exclude this file from your anti-virus scanning node-pty\build\Release\winpty-agent.exe

pty.js

This project is forked from chjj/pty.js with the primary goals being to provide better support for later Node.JS versions and Windows.

License

Copyright (c) 2012-2015, Christopher Jeffrey (MIT License).
Copyright (c) 2016, Daniel Imms (MIT License).
Copyright (c) 2018, Microsoft Corporation (MIT License).