Docker Shell (@synchjs/docker-shell)

@synchjs/docker-shell is a powerful TypeScript library designed to establish secure, interactive, and manageable terminal sessions between a host client (web or CLI) and any remote environment (Docker container or server).

It leverages Socket.IO (and optionally Elysia) for reliable realtime communication and node-pty for robust cross-platform Pseudo-Terminal (PTY) emulation, ensuring full support for interactive CLI tools like vim, htop, nano, and colored outputs.

Features

• 🚀 Full TTY Emulation: Uses node-pty for true terminal behavior (colors, raw mode, resizing).
• 🛡️ Intelligent Proxy: Includes a TerminalProxy component to intercept, inspect, and block traffic (e.g., prevent rm -rf commands).
• 🔌 Dual Backend Support: Run the proxy/server with standard Socket.IO or high-performance Elysia (Bun) websockets.
• 🐳 Docker Ready: Designed to work effortlessly inside containers.
• 🪟 Cross-Platform: Fully compatible with Linux, macOS, and Windows.
• ⚡ TypeScript First: Written in TypeScript with complete type definitions.

Installation

# Using bun (Recommended)
bun add @synchjs/docker-shell socket.io socket.io-client node-pty

# Using npm
npm install @synchjs/docker-shell socket.io socket.io-client node-pty

Note: If you use the Elysia backend feature, you may need to install elysia.

Architecture

This library provides three main components:

1. TerminalServer: Runs on the target machine (e.g., inside Docker). Spawns actual shell processes (bash, powershell) using node-pty.
2. TerminalProxy (Optional): A "Middle-man" server that sits between the Client and key Server. It can filter commands, log traffic, or enforce security policies.
3. TerminalClient: Runs on the frontend or host machine. Connects to the Server (or Proxy) to render the terminal.

Usage

1. Server Setup (Target Machine / Docker)

Runs the actual shell process.

import { TerminalServer } from "@synchjs/docker-shell";

// Start server on port 9000
const server = new TerminalServer(9000);

console.log("Terminal Server running on port 9000...");

2. Proxy Setup (Optional - Interceptor)

The proxy allows you to inspect traffic between the client and the server. You can listen on a new port (e.g., 9001) and forward traffic to the real server (9000).

import { TerminalProxy } from "@synchjs/docker-shell";

new TerminalProxy({
  port: 9001,
  targetUrl: "http://localhost:9000",
  backend: "socket.io", // or "elysia"
  interceptor: async ({ direction, event, payload, socketId }) => {
    // SECURITY: Block dangerous commands
    if (direction === "client-to-server" && event === "create") {
      const command = payload[0]?.command;
      if (command && command.includes("rm -rf")) {
        console.warn("⚠️ Blocked dangerous command!");
        return false; // Drop this packet
      }
    }
    return true; // Allow packet
  },
});

3. Client Setup (Frontend / Host)

Web Client (React/Vue/Vanilla)

import { TerminalClient } from "@synchjs/docker-shell";

// Connect to the Proxy (9001) or directly to Server (9000)
const client = new TerminalClient("http://localhost:9001");

client.on("out", (data) => {
  // render data.message to xterm.js or console
  console.log(data.message);
});

// Start a session
await client.createSession("session-1", "ls -la");

// Send input
client.write("session-1", "pwd\n");

API Documentation

TerminalServer

• constructor(port: number): Starts the server.
• Uses node-pty internally for robust terminal emulation.

TerminalProxy

• constructor(options: TerminalProxyOptions)
  • port: Port to listen on.
  • targetUrl: URL of the real TerminalServer.
  • backend: "socket.io" (default) or "elysia".
  • interceptor: Async function to filter events. Returns true (allow) or false (block).

TerminalClient

• constructor(url: string): Connects to server/proxy.
• createSession(id, command): Spawns a shell.
• write(id, data): Sends keystrokes.
• killSession(id): Terminates the session.

License

MIT