Building a web shell from scratch

You’ve probably used tools like AWS Session Manager or the Google Cloud Console - powerful, browser-accessible platforms that let you manage cloud sessions and infrastructure remotely. In this blog post, we’ll show you how you can build a similar web-based session manager from scratch, giving you full control over remote access, monitoring, and session management.

Requirements

• Operating System: A Unix-like environment (Linux, macOS) with a functional terminal.
• Dependencies: Node.js (or your server-side runtime of choice) and any required packages for handling WebSocket connections and PTY spawning.
• Shell Capabilities: The web shell should support running arbitrary shell commands with real-time output, similar to a native terminal.

Architecture

This architecture describes a web-based shell interface using WebSocket communication to interact with a server-side pseudo-terminal (PTY).

On the client side, a Terminal Emulator is bound with WebSocket IO, providing a real-time interactive shell interface in the browser. This Shell component connects to the WebShellServer running on the server via WebSocket.

The WebShellServer component handles incoming WebSocket connections from clients. Upon connection, it creates and binds a PTY process on the server, linking its standard input/output streams to the WebSocket stream.

This architecture allows seamless bidirectional communication between the client-side terminal and the server-side PTY, enabling users to execute commands remotely as if they were interacting directly with a native terminal session. The design ensures real-time command execution, output streaming, and responsive interaction, making it ideal for building web-based terminal solutions, remote administration tools, or cloud-based development environments.

Implementation

A simple implementation example is available here: https://github.com/adaptive-scale/webshell

git clone https://github.com/adaptive-scale/webshell.git
cd webshell
make run

Once running, you can access the web shell at http://localhost:8080/terminal. This project includes a basic Node.js server that creates a PTY process and bridges the input/output over WebSocket to the browser client. You can customize and extend this example to add security, user management, logging, and additional features as needed.

Improvements

• The webshell needs an authentication layer. Ideally you would want to add oauth integrated with organization's user directory.
• There is logging and activity tracking missing from the project
• Socket connections can be a bit wonky.