Skip to main content
`Ctrl`+`K`

# Using the TermSocket handler

`terminado.TermSocket` is the main API in Terminado. It is a subclass of `tornado.web.WebSocketHandler`, used to communicate between a pseudoterminal and term.js. You add it to your web application as a handler like any other:

    app = tornado.web.Application([
            # ... other handlers ...
            (r"/websocket", terminado.TermSocket,
                {'term_manager': terminado.SingleTermManager(shell_command=['bash'])}),
        ], **kwargs)

Now, a page in your application can connect to `ws://<host>/websocket`. Using `terminado/_static/terminado.js`, you can do this using:

    make_terminal(target_html_element, {rows:25, cols:80}, "ws://<host>/websocket");

Warning

`TermSocket` does not authenticate the connection at all, and using it with a program like `bash` means that anyone who can connect to it can run commands on your server. It is up to you to integrate the handler with whatever authentication system your application uses. For instance, in IPython, we subclass it like this:

    class TermSocket(terminado.TermSocket, IPythonHandler):
        def get(self, *args, **kwargs):
            if not self.get_current_user():
                raise web.HTTPError(403)
            return super(TermSocket, self).get(*args, **kwargs)

## Terminal managers

The terminal manager control the behaviour when you connect and disconnect websockets. Terminado offers three options:

class terminado.SingleTermManager(**kwargs: Any)

  All connections to the websocket share a common terminal.

class terminado.UniqueTermManager(max_terminals: int | None = None, **kwargs: Any)

  Give each websocket a unique terminal to use.

class terminado.NamedTermManager(max_terminals: Any = None, **kwargs: Any)

  Share terminals between websockets connected to the same endpoint.

You can also define your own behaviours, by subclassing any of these, or the base class. The important methods are described here:

class terminado.TermManagerBase(shell_command: str, server_url: str = '', term_settings: Any = None, extra_env: Any = None, ioloop: Any = None, blocking_io_executor: Any = None)

  Base class for a terminal manager.

  get_terminal(url_component: Any = None) → PtyWithClients

    Override in a subclass to give a terminal to a new websocket connection

    The `TermSocket` handler works with zero or one URL components (capturing groups in the URL spec regex). If it receives one, it is passed as the `url_component` parameter; otherwise, this is None.

  new_terminal(**kwargs: Any) → PtyWithClients

    Make a new terminal, return a `PtyWithClients` instance.

  start_reading(ptywclients: PtyWithClients) → None

    Connect a terminal to the tornado event loop to read data from it.

  client_disconnected(websocket: Any) → None

    Override this to e.g. kill terminals on client disconnection.

This may still be subject to change as we work out the best API.

In the example above, the terminal manager was only attached to the websocket handler. If you want to access it from other handlers, for instance to list running terminals, attach the instance to your application, for instance in the settings dictionary.