Terminado

Warnings

• breaking Python 3.7 support was removed in version 0.18.0. Users on Python 3.7 or older must upgrade their Python environment or use an older `terminado` version (<=0.17.x).
  Fix: Upgrade Python to 3.8 or higher. If unable to upgrade Python, pin `terminado` to `<0.18.0`.
• breaking Python 3.6 support was officially dropped in version 0.13.0. Users on Python 3.6 must upgrade their Python environment or use an older `terminado` version (<=0.12.x).
  Fix: Upgrade Python to 3.7 or higher. If unable to upgrade Python, pin `terminado` to `<0.13.0`.
• gotcha The `TermSocket` handler does not implement any authentication or authorization by default. Exposing it directly (especially with a shell command) without proper security measures allows anyone who can connect to run arbitrary commands on the server. This is a significant security risk.
  Fix: Subclass `terminado.TermSocket` and override the `get` method to integrate with your application's authentication system (e.g., as shown in Jupyter's `IPythonHandler` example). Ensure only authenticated and authorized users can access the websocket endpoint. Listen only on `localhost` unless explicitly needed and secured.
• gotcha Terminado is a *backend* library. It provides the server-side Python component for a terminal, but requires a client-side JavaScript terminal emulator (such as Xterm.js) to provide a complete interactive terminal experience in a web browser. The Python library does not include a GUI itself.
  Fix: Integrate a JavaScript frontend library (e.g., Xterm.js) into your web application and configure it to connect to the `TermSocket` WebSocket endpoint provided by Terminado.
• gotcha Older versions of Terminado (prior to 0.16.0) had a bug where large stdin writes could cause the Tornado server to hang, leading to unresponsive terminals.
  Fix: Upgrade `terminado` to version 0.16.0 or newer to benefit from the fix for this issue. Ensure your application handles large inputs gracefully.

Install

• pip install terminado tornado ptyprocess Install with core dependencies

Imports

• TermSocket

  from terminado.websocket import TermSocket

  TermSocket is found within the 'websocket' submodule, not directly under 'terminado'.
• SingleTermManager

  from terminado.management import SingleTermManager

  Terminal managers are located in the 'management' submodule.
• UniqueTermManager

  from terminado.management import UniqueTermManager

• NamedTermManager

  from terminado.management import NamedTermManager

Quickstart

This quickstart sets up a basic Tornado web application with a `TermSocket` handler. It creates a single terminal instance managed by `SingleTermManager` and exposes it over a WebSocket endpoint. A simple HTTP handler is also included for initial access. Note that a client-side JavaScript terminal emulator (like Xterm.js) is required to interact with this backend. The `TERMINADO_SHELL`, `PORT`, and `HOST` environment variables can be used to customize the shell, port, and host respectively.

import os.path
import tornado.web
import tornado.ioloop
from terminado.websocket import TermSocket
from terminado.management import SingleTermManager

# NOTE: For a full web demo with a client-side terminal, you would also need
# tornado_xstatic and XStatic-term.js, and a corresponding HTML template.
# This example focuses on the Python server-side setup.

class MainHandler(tornado.web.RequestHandler):
    def get(self):
        self.write("Hello from Terminado server!\n")
        self.write("To use, connect a WebSocket-based terminal client (e.g., Xterm.js) to ws://localhost:8765/websocket")

if __name__ == "__main__":
    # Use 'bash' for Linux/macOS or 'cmd.exe' for Windows
    shell_command = os.environ.get('TERMINADO_SHELL', 'bash' if os.name != 'nt' else 'cmd.exe')
    term_manager = SingleTermManager(shell_command=[shell_command])

    handlers = [
        (r"/websocket", TermSocket, {"term_manager": term_manager}),
        (r"/", MainHandler),
    ]

    app = tornado.web.Application(handlers)
    port = int(os.environ.get('PORT', 8765))
    host = os.environ.get('HOST', 'localhost') # Listen on localhost for security
    app.listen(port, host)
    print(f"Terminado server started on http://{host}:{port}")
    print(f"WebSocket endpoint at ws://{host}:{port}/websocket")
    print(f"Using shell: {shell_command}")
    print("Press Ctrl+C to stop.")
    try:
        tornado.ioloop.IOLoop.current().start()
    except KeyboardInterrupt:
        print("\nServer stopped.")
    finally:
        term_manager.shutdown()