jenai

Open a real terminal in a Google Colab cell — including the free tier.

!pip install jenai
%load_ext jenai
%xterm

What it is

A terminal server, a single-page client, and a notebook magic. The client is one <div>; there is no toolbar, no status bar and no settings panel. The server is a hand-written asyncio HTTP/1.1 + RFC 6455 implementation that drives a real pty from the event loop itself — no threads in the data path, no StreamReader, and one WebSocket per tab carrying raw bytes.

Measured on the same machine, against the previous implementation:

Run make bench for the live numbers on your own hardware.

Options

%xterm height=1000 port=10001

Development

Requires Python 3.11+ and Node 20+.

make install     # pip install -e '.[dev]' plus the client toolchain
make build       # bundle the client into jenai/client/dist/index.html
make test        # the whole suite (add -m "not slow" to skip shells/browser)
make lint        # ruff check, ruff format --check, mypy --strict, tsc --noEmit
make bench       # echo latency, ping, output and input throughput
make profile     # cProfile report: server, codec and bundle

Layout

jenai/
  app.py          CLI entry point, uvloop setup, readiness handshake
  server.py       asyncio.Protocol HTTP+WebSocket server
  wsproto.py      RFC 6455 codec
  httpproto.py    HTTP/1.1 parsing and rendering
  assets.py       in-memory, pre-compressed static assets
  pty_session.py  pty sessions driven from the event loop
  wire.py         control-message protocol shared with the browser
  notebook.py     the %xterm magic
  client/
    build.ts      esbuild -> one inlined index.html
    src/          TypeScript: transport, terminal, protocol

Testing

tests/ runs against real sockets, real forked shells and — where Playwright is installed — a real headless Chromium. The browser tests are not decoration: they are what caught the client never wiring onData to the transport, which no Python test could have seen.

make test                     # everything
make test-fast                # no shells, no browser
make test-browser             # Playwright only
pip install playwright && playwright install chromium   # for the browser tests

Design notes

• Binary frames carry pty bytes. The old client base64-encoded input into a URL path and output into JSON; both put a ceiling on what a user could type or what the server could send. Binary frames have neither the ceiling nor the encoding cost.
• No client-side batching. The old client accumulated keystrokes for 100 ms before sending. Every keystroke now goes out immediately, and xterm.js coalesces renders on its own schedule.
• Back-pressure pauses the pty. If a browser falls behind, the server stops reading the pty master instead of buffering output in Python, so a runaway cat cannot balloon the server's memory.
• A page reload re-attaches. Session ids live in sessionStorage; the server keeps the shell alive across the reconnect.
• The bundle is inlined. One request, no waterfall, and .gz/.br siblings the server serves straight from memory.

Screenshots

Credits

Built on xterm.js and forked from colab-xterm, which got the idea.